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.
6. Go validation must follow CI order - For Go changes, run from the repo root, sequentially: go build ./..., then go vet ./..., then go test ./.... Fix a failed stage before advancing to the next. The vet checks run implicitly by go test are only a subset and do not replace the explicit go vet ./... gate. For concurrency changes, also run go test -race on the affected packages. Complete these checks before reporting the change ready to commit or push; report exact commands and any failures or skipped checks. Device tests do not replace local gates.
7. Design and verify latency when implementing features - Treat response time as part of functional correctness, especially for touch, buttons, voice, and other direct interactions. Before implementation, identify the path from user action to feedback and readiness, set a concrete latency target, and inspect blocking I/O, network calls, polling, debounce, and cold initialization. Keep immediate feedback and input handling independent of slow work where possible, without signaling readiness before the system can accept input. When adding asynchronous work, preserve ordering, cancellation, and bounded resource usage. Before declaring an interactive feature complete, measure latency as well as functional behavior: cover first use, repeated actions, and slow dependencies on the target hardware when authorized. For latency fixes, report comparable before/after measurements, their exact boundaries, and any unverified device or end-to-end behavior. Passing functional tests alone does not demonstrate responsive UX.
8. Robot behavior must read as a living thing, not a machine - Before shipping any autonomous motion, sound, light, or speech, ask: does the lamp act like a human, or like a living thing? Would a person or a pet do this here? Judge what the user sees, not whether the algorithm reaches its goal. Unprompted behavior stays small and natural: a lamp that turns to a voice and finds nobody glances left and right and lets it go; it does not scan the room at 18 positions like a WiFi camera. Exhaustive, mechanical behavior is only for when the user explicitly asks for it (e.g. "look around for my keys"). When a design passes its tests but would look odd, awkward, or robotic to someone in the room, it is not done.

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.
• Use English by default for all user-facing communication, including progress updates, questions, and final responses. Switch to Vietnamese or another language only when the user explicitly requests it; do not infer a language switch solely from the language of their message.
• 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.

Waiting for tools and background jobs

Avoid model turns that only ask whether a job has finished.

• Follow the active tool's completion contract. If it explicitly delivers the result automatically, do independent work or use its supported yield/wait mechanism. End a turn to await delivery only when the tool explicitly guarantees that it will resume the task; never assume a wakeup.
• Do not use shell sleep loops, repeated ps / pgrep / top, or repeated log/status reads to wait for a job that already has a completion mechanism. Targeted process/log inspection is still appropriate to diagnose a failure or a suspected stall.
• Retain the returned handle and use its matching continuation tool. In Codex, an exec_command session ID uses write_stdin; a yielded functions.exec cell ID uses functions.wait. For agents/tasks, use the available native wait tool and preserve any returned cursor. These handles are not interchangeable, and receiving one does not mean the job succeeded.
• For a long-running job, use a bounded wait suited to its expected duration (normally 30-60 seconds, within the active tool and communication limits). Avoid repeated zero/short-timeout checks; read only new output and report meaningful progress instead of narrating unchanged status.
• When an external job has no notification or native wait support, use a bounded watcher or read-only polling with backoff and an overall deadline. Do not rerun the original operation just to obtain its status.
• Inspect the final output and exit code or terminal status before claiming completion. A timeout, background handle, or quiet log is not success.

This governs coding-agent orchestration. It does not remove application/API polling, test synchronization, or service-readiness checks required by their own contracts.

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