anda-bot: Instructions file for Codex

AGENTS.md

Guidance for coding agents working in this repository. This file applies to the entire tree unless a more specific AGENTS.md is added in a subdirectory.

Project Overview

Anda Bot is a local-first Rust AI agent with long-term memory, subagents, a TUI, voice support, browser integration, cron automation, and IM channel runtimes. The main binary is anda, implemented by the Rust package anda_bot.

The repository also contains:

• chrome-extension/: Svelte + TypeScript Chrome Side Panel client.
• desktop/: Electron + Svelte desktop client.
• website/: SvelteKit marketing/support site.
• docsite/: Docusaurus documentation site with localized docs.
• skills/: runtime skill packages distributed with the project.
• scripts/: release/install helper scripts.

Agent Workflow

• Work independently as the current agent. Do not spawn or delegate work to subagents.
• Before editing, run git status --short, confirm the current branch, and inspect existing diffs in the files you intend to change. Preserve the user's existing work; do not overwrite or revert unrelated files or changes.
• Use rg for search and focused reads before editing. Do not assume module boundaries from filenames alone.
• Before committing, review the final diff and stage only the files or hunks belonging to the requested task.
• At completion, briefly summarize the changes, the checks actually run and their results, and any checks not run or blocked. Never report an unrun check as passing. When committing, include the branch and commit ID in the summary.

Development Rules

• Keep changes scoped to the subsystem requested. Avoid broad refactors unless they are necessary to make the requested behavior correct.
• Fix the root cause and keep the implementation direct and clear. Do not add complexity for extreme or speculative scenarios beyond the task's needs.
• Prefer existing project patterns over new abstractions. This codebase already has clear boundaries for config, daemon startup, engine tools, channels, transcription, TTS, cron, and the TUI.
• When refactoring, remove obsolete branches and abstractions in the affected code, and update the corresponding callers, comments, and tests.
• Never use oneOf, anyOf or allOf in a model-facing schema: tool parameters and structured-output schemas. Anthropic rejects them at the top level of a tool's input_schema and fails the whole request with a 400 (KIP's top-level oneOf once left Brain formations stuck "waiting to be organized" on Claude); strict modes reject them anywhere. Write nullable fields as "type": ["string", "null"], tagged variants as one object with an enum discriminator, and check new tool schemas with util::json_schema::assert_openai_strict_parameters. Schemas we receive from Brain or Engine follow the same rule in their own repositories.
• Do not commit secrets, tokens, generated local state, or user data. Runtime state normally belongs under ~/.anda; repository examples must use placeholders.
• When changing public behavior, update the relevant docs and examples. The top-level README.md and README_cn.md are paired and should stay in sync.
• If user-facing docs under docsite/docs/ change, keep localized counterparts aligned where they already exist, especially docsite/i18n/zh-Hans/....