autonomous-os

Imported from autonomous-ai/autonomous-os (AGENTS.md). Install upstream with npx skills add autonomous-ai/autonomous-os. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex and other coding agents when working in this repository. Treat CLAUDE.md as the upstream source of truth; this file is the Codex-compatible mirror of those project rules.

Multi-IDE Rules

This repo is developed across multiple AI-assisted environments. The following rules apply to all code changes:

1. Update docs on code change - When changing behavior, architecture, or APIs, update both the English and Vietnamese docs. Keep numbers, flows, endpoints, and states accurate with the code. Platform docs are in docs/; lamp-specific docs are in robots/lamp/docs/.

   Platform docs (docs/ + docs/vi/):

   Code area	English doc	Vietnamese doc
   os-server, API, startup	docs/os-server.md	docs/vi/os-server_vi.md
   Setup flow, provisioning	docs/setup-flow.md	docs/vi/setup-flow_vi.md
   Web UI, configuration pages	docs/web-ui.md	docs/vi/web-ui_vi.md
   Flow Monitor (turn pipeline, JSONL, SSE)	docs/flow-monitor.md	docs/vi/flow-monitor_vi.md
   Overall structure	docs/overview.md	docs/vi/overview_vi.md
   MQTT, dispatch, publish	docs/mqtt.md	docs/vi/mqtt_vi.md
   OTA, bootstrap	docs/bootstrap-ota.md	docs/vi/bootstrap-ota.md
   Speech emotion recognition (SER)	docs/speech-emotion.md	docs/vi/speech-emotion_vi.md
   Realtime voice agent (HAL realtime, Gemini Live / OpenAI Realtime, delegate)	docs/realtime-voice.md	docs/vi/realtime-voice_vi.md
   Perception service (cloud DL inference), load balancer, encryption, models	docs/perception-service.md	docs/vi/perception-service_vi.md
   Hermes agent backend (agent_runtime, runtimes/hermes)	docs/agentic/hermes.md	docs/vi/agentic/hermes_vi.md
   PicoClaw agent backend (agent_runtime, runtimes/picoclaw, WebSocket)	docs/agentic/picoclaw.md	docs/vi/agentic/picoclaw_vi.md
   Adding/changing an agentic backend (AgentGateway contract, switch, install/presync, migration, skills, hooks, reset)	docs/agentic/adding-agent-runtime.md	docs/vi/agentic/adding-agent-runtime_vi.md
   Safety engine (SAFETY.md bounds, deterministic enforcement gate)	docs/safety.md	docs/vi/safety_vi.md
   Device telemetry (adding a tracker, hal/telemetry, system/telemetry, /api/telemetry/event)	docs/telemetry.md	docs/vi/telemetry_vi.md
   Voice response metrics (hal/telemetry, system/telemetry, /api/telemetry/event)	docs/voice-metrics.md	docs/vi/voice-metrics_vi.md

   Lamp-specific docs (robots/lamp/docs/ + robots/lamp/docs/vi/):

   Code area	English doc	Vietnamese doc
   LED, effects, states, animations	robots/lamp/docs/led-control.md	robots/lamp/docs/vi/led-control_vi.md
   Sensing behavior, sound escalation, reactions	robots/lamp/docs/sensing-behavior.md	robots/lamp/docs/vi/sensing-behavior_vi.md
   Sensing threshold tuning	robots/lamp/docs/sensing-tuning.md	robots/lamp/docs/vi/sensing-tuning_vi.md
   Habit tracking, pattern building, habit-aware nudge phrasing	robots/lamp/docs/habit-tracking.md	robots/lamp/docs/vi/habit-tracking_vi.md
   Vision tracking, object follow, servo track	robots/lamp/docs/vision-tracking.md	robots/lamp/docs/vi/vision-tracking_vi.md
   Physical controls (GPIO button, TTP223 touchpad, gestures, pet response)	robots/lamp/docs/physical-controls.md	robots/lamp/docs/vi/physical-controls_vi.md
   Autonomous Buddy (Mac companion app)	integrations/companions/autonomous-buddy/docs/autonomous-buddy.md, integrations/companions/autonomous-buddy/docs/autonomous-buddy-mvp.md, integrations/companions/autonomous-buddy/docs/release-signing.md	integrations/companions/autonomous-buddy/docs/vi/autonomous-buddy_vi.md, integrations/companions/autonomous-buddy/docs/vi/autonomous-buddy-mvp_vi.md, integrations/companions/autonomous-buddy/docs/vi/release-signing_vi.md
   Security test checklist	robots/lamp/docs/security-test.md	(no vi version)

2. Comments in English - Project standard.

3. Code is the single source of truth - Docs reflect code, not the other way around.

4. Do not commit binary artifacts - Version is injected via ldflags at build time.

5. Web/TSX lint is a required quality gate - For every change under system/web/, work freely on the implementation but finish with both npm run lint and npm run build from system/web/. Do not hand off a change with ESLint warnings or errors, TypeScript errors, or a skipped validation command. Fix React Hook diagnostics by restructuring the code; do not silence them with eslint-disable unless the exception is narrowly scoped, documented in English with why it is safe, and has no practical compliant alternative. Report the exact commands run and any limitation.

See docs/DEV-MULTI-IDE.md for full conventions.

Working Style

• The user reviews and commits by hand. Do not create commits unless explicitly asked. When asked: git add the exact files of that change (never git add -A), check git status --short for unrelated dirty or untracked files and leave them alone, then commit with a single-line message and nothing else in it — no Co-Authored-By trailer, no "Generated with" footer, no body. Commit only; do not push unless told to.
• Work in small, reviewable chunks. When a task spans multiple concerns, split it by concern and verify each batch before moving to the next.
• Stay in scope. Flag unrelated issues instead of fixing them opportunistically.
• Verify with concrete evidence such as focused tests, builds, greps, bash -n, or compile checks. Report what was and was not verified.
• Do not "clean up" inherited drift such as unrelated gofmt churn, duplicate dependency metadata, or upstream-preserved style unless it is required for the task.
• Respond to the user in Vietnamese unless they request otherwise.
• Do not auto-deploy to devices. Default to repo changes plus local verification; any on-device SSH/SCP/restart step is opt-in and must be confirmed first.

Parallel Work / Subagents

When work can be split across independent, file-scoped tasks, use available parallelism instead of doing everything sequentially. In Codex, prefer multi_tool_use.parallel for independent local reads/checks, and use subagents only when the tool is available and the overhead is justified.

Common cases in this repo:

• Repetitive edits across many files, such as rebranding strings across EN + VI docs: split by file or language, with exact rules and a verification grep.
• Long-running builds or cross-compile checks, such as swift build or GOOS=linux GOARCH=arm64 go build: run in parallel/background when possible and continue with independent work.
• Repo-wide audits, such as stale paths after folder moves or broken cross-refs: use audit-only scope unless edits are explicitly part of the task.
• Independent English and Vietnamese doc updates after a code change: keep both sides consistent and verify matching numbers, endpoints, states, and flows.

Rules:

• Brief any delegated worker with goal, context, exact files/scope, verification step, and concise report format.
• Do not delegate when the overhead is larger than the work itself, especially for one or two quick edits in files already open.
• Trust but verify: spot-check actual diffs and run focused greps/tests before considering delegated work done.

Device Access Rules

• Always ask the user before running any sshpass or ssh command to the Pi. Do not SSH automatically.
• Pi SSH: ssh pi@<IP> (credentials stored in the team password manager; IP varies per session).

Harness integration context

Before changing skills/harness-use, system/harness or the OS Harness UI/API, read the integration context and ownership and its Vietnamese counterpart. Harness app/device support is maintained by a separate team in autonomous-harness and autonomous-harness-desktop. This repo owns the OS client and skill only; keep implementation edits here. Verify cross-repository contract changes against the Harness team's current code and coordinate them rather than inventing another pairing flow, transport or credential. Buddy stays independent.

Project Overview

Autonomous is an open-source OS for physical AI agents. The Go backend (system) provides device onboarding (WiFi, LLM provider, messaging channel setup), OTA updates, and agent gateway integration. The brain is a swappable agentic runtime (OpenClaw, Hermes, or any LLM + skills + memory).

Go module: go.autonomous.ai/os (rooted at repo root — covers system/ and runtimes/) | Go 1.24 | Target: Linux ARM64

Build & Development Commands

All targets run from the repo root via the top-level Makefile.

# Build Go services (cross-compiles to linux/arm64)
make os-build                # Builds os-server binary
make os-build-bootstrap      # Builds bootstrap-server binary

# Code generation (Google Wire DI)
make os-generate             # Runs from repo root: GOFLAGS=-mod=mod go generate ./...

# Lint + tests (Go)
make os-lint                 # golangci-lint run (repo root, covers runtimes/)
make os-test                 # go test ./... (repo root, covers runtimes/)

# HAL (Python hardware runtime, hal)
make hal-dev                 # Install deps + run HAL locally
make hal-lint                # Catch broken local imports + undefined names
make hal-test                # Run HAL tests

# Web frontend (React/Vite/Tailwind in system/web)
make web-install             # npm install
make web-dev                 # Vite dev server
make web-build               # Production build to dist/
cd system/web && npm run lint  # Required after every web/TSX change
cd system/web && npm run build # Required type-check + production build

Go version is injected at build time via ldflags. HAL/web versions live in system/VERSION_OS_SERVER and hal/VERSION_HAL and are auto-bumped by the make upload-* release targets — do not hand-edit for releases.

Architecture

Two Executables

• system/cmd/os-server/main.go - Main HTTP API server (Gin). Handles device setup, network management, LED control, health checks, and agent gateway integration.
• system/cmd/bootstrap/main.go - OTA bootstrap worker. Periodically checks for and applies updates.

Dependency Injection

Uses Google Wire for compile-time DI. After changing provider signatures, run make os-generate to regenerate wire_gen.go files.

Package Layout

Agentic runtimes - runtimes/ (repo root): swappable backends, one folder per brain: runtimes/{openclaw,hermes,picoclaw,codex,claudecode}. Selected by system/agent (AgentGateway factory).

Go backend - system/ (single Go module rooted at the repo root):

• system/<domain>/ - System managers, one folder per diagram chip (ambient, beclient, buddy, device, healthwatch, intent, monitor, network, skills, statusled, vision) plus system/agent/ (AgentGateway factory + migration).
• system/server/ - HTTP layer: Gin router, handlers by domain (delivery/http/handler.go convention); server/serializers/, server/config/.
• system/bootstrap/ - OTA worker: metadata fetching, update execution, state persistence.
• system/domain/ - Shared data structures.
• system/lib/ - Shared libraries (mqtt, core/system, i18n, logger, hal HAL client, safego, ...).
• system/web/ - React 19 + TypeScript + Vite + Tailwind CSS 4 SPA.

HAL - hal/ (Python hardware runtime, FastAPI on :5001):

• drivers/ - Hardware drivers by subsystem (rgb, motors, voice, sensing, display, gpio_button, ...).
• board/ - Per-board profiles (pin maps, debounce).
• routes/ - FastAPI route modules (servo, led, camera, audio, emotion, ...).

OS-level dirs (repo root): skills/ (agent skills), robots/ (per-device declarations + docs; robots/contract/ device specs, robots/contract/cts/ compliance tests), scripts/imager/ (OrangePi image build), scripts/ (setup + OTA upload), integrations/perception-service/, integrations/companions/.

API Response Format

All HTTP endpoints return:

{"status": 1, "data": {}, "message": null}

on success, and:

{"status": 0, "data": null, "message": "error"}

on failure.

Configuration

Config lives in config/config.json (path relative to the os-server working dir) and is managed by system/server/config/config.go. It supports a notification channel for config change propagation.

Coding Standards

Error Handling

if err != nil {
    return fmt.Errorf("operation: %w", err)
}

Always wrap errors with useful context.

Logging

log.Println("[component] message")
log.Printf("[component] formatted %v", value)

Goroutines

Always use context.Context for cancellation. Background goroutines must respect ctx.Done().

Validation

Use go-playground/validator for struct validation. Validate at the HTTP handler level before passing data to services.

Naming (paths under system/)

• Handlers: server/<domain>/delivery/http/handler.go
• Services: <domain>/service.go (system managers live at system/<domain>/, e.g. ambient/service.go)
• Wire providers: server/wire.go, bootstrap/wire.go
• Domain types: domain/<type>.go