Working With Anode

This is the page to read after install. It is about how to talk to Anode, when to use each surface, and how to keep a thread useful.

How To Prompt

Be direct. The best prompts give Anode three things:

1. the outcome you want;
2. the boundaries it should respect;
3. the check that proves the work is done.

Good:

Find why TestConfigProfiles fails, make the smallest fix, and rerun that test.
Keep unrelated files untouched.

That is enough. Anode has a target, a scope, and a check. It can inspect the repo, choose tools, ask for approval when needed, edit files, and run the test.

Also good:

Only plan how to add OAuth login. Read the routing, auth, config, and tests.
Do not write code yet.

Review the current diff for correctness and missing tests. Lead with concrete
findings and file references.

Start With Inspection

Ask Anode to inspect first when the project is unfamiliar:

Read the entrypoints, config files, scripts, tests, and existing manual pages.
Explain how this project works before changing anything.

For a fast read-only pass from the shell:

anode -x --profile find "map the project entrypoints, configuration, scripts, and tests"

Use --profile find when you want codebase discovery without broad write access. Use --profile review for read-only review behavior. Use --profile study when you expect a longer investigation.

Make A Small Change

The TUI is the most comfortable interface for edits:

anode

Then prompt:

Add a --dry-run flag to the cleanup command. Follow the existing CLI style,
update tests, and run the focused tests before finishing.

Useful slash commands while it works:

Command	Use it when
/status	You want to confirm model, profile, tools, web, and MCP state.
/plan	The change has more than one step.
/execute	You approved the current plan and want Anode to carry it out.
/changes	You want to see files changed by the current session.
/cancel	The run is going in the wrong direction.
/steer	You need to add guidance to queued work.
/commit	You want Anode to prepare a commit from its change ledger.

Good small-change prompts:

Rename this flag in the CLI and tests only. Do not change config behavior.

Add validation for empty provider IDs. Use the existing error style and add a
focused unit test.

Update the quickstart example to match the current install command and check
links afterward.

Debugging

Start with the failing command, not a theory:

Run `go test ./internal/config -run TestProfiles`. Investigate the failure,
explain the root cause, make the smallest fix, and rerun the same test.

If the failure might cross packages:

Run the failing test first. Trace the data flow from CLI flags into runtime
options. Fix only the broken behavior and then run the smallest useful test
set.

For headless debugging:

anode -x --profile study "run the failing test, find the root cause, fix it, and rerun the test"

Review Work

Use review mode when you want Anode to inspect the current diff without making edits:

anode review
anode review --base main
anode review --base main --checks

Review mode reads git status, staged and unstaged diffs, base diffs when you provide --base, changed filenames, and previews for untracked files. With --checks, it also loads project check files from .agents/checks/*.md and nearest scoped check directories.

Good review prompts:

anode review "focus on security regressions and missing tests"

anode review --base main "look for behavior changes in config loading"

Use --stream-json when another process needs structured review events:

anode review --base main --stream-json

Plan Bigger Work

For multi-file changes, ask for a plan and keep approval points explicit:

Plan the migration from the old config key to the new key. Read the CLI,
config loader, tests, and manual pages first. Do not edit until the plan is
clear.

Inside the TUI:

/plan

Then after reviewing the plan:

/execute

Plan mode tracks steps, validation, and change status in the TUI. It is useful when the work has hidden coupling or needs careful sequencing.

Run In Automation

Use headless mode for scripts:

anode -x "summarize the current git diff"

Use stream JSON when a caller needs events:

anode -x "run tests and summarize failures" --stream-json

Use stdin when the prompt is generated by another command:

git diff --stat | anode -x --stream-json

Use multi-turn JSON input when you are building a programmatic conversation:

anode -x --stream-json --stream-json-input

The stream input protocol is line-delimited JSON. See headless.md and automation.md for event names and examples.

Run In The Background

Use the daemon when work should survive your current terminal session:

anode daemon
anode runs start "investigate the flaky auth test and report the likely cause"
anode runs list
anode attach <run-id>

The daemon exposes REST endpoints and server-sent events. Runs are kept in the daemon process; the run list is not persisted across daemon restarts.

More: daemon.md.

Teach Project Rules

Add AGENTS.md at the repository root for project-wide behavior:

# AGENTS.md

- Use `rg` for search.
- Keep changes small and explain tradeoffs before broad refactors.
- Run `go test ./...` before finishing code changes.
- Do not edit generated files.

Add another AGENTS.md in a subdirectory when rules only apply there. Anode loads scoped instruction files from the current workspace and subdirectories, with AGENTS.md preferred over AGENT.md and CLAUDE.md in the same directory.

You can include small referenced files from guidance with @path includes. The include must stay inside the workspace. Glob includes expand to at most 10 regular, non-symlink files so a guidance file cannot accidentally pull in the whole repository.

More: agents-and-skills.md.

Use Specialized Help

Anode has built-in tools and profiles for different jobs:

Need	Use
Fast code search and explanation	--profile find
Longer investigation	--profile study
Read-only review behavior	--profile review or anode review
A focused second pass	ask Anode to use the oracle tool
A bounded subtask	ask Anode to use the task tool
Tool and command inventory	anode tools list and anode tools show <name>
Language-server help	enable LSP and use the LSP tool when a server is available

Examples:

Use oracle to double-check whether this config migration misses any callers.

Use a task for a read-only pass over tests while you inspect the CLI path.

Keep Threads Clean

Use a new session for unrelated work:

/new

Find previous work:

/sessions
/threads

Resume saved work:

/resume

Create a handoff when another person or process needs context:

/handoff

Use /context and /repo to inspect what Anode currently knows about the workspace. Use /memory for local project memory.

Prompt Recipes

Understand a project:

Read the repository before answering. Summarize what the project is, how it is
run, where config lives, where tests live, and what the main risks are.

Make a focused change:

Implement <change>. Keep the patch narrow. Follow existing style. Add or update
the smallest useful test. Run the focused test and tell me what passed.

Review a diff:

Review this for correctness, security, and missing tests. Lead with concrete
findings and file references. Do not summarize unless there are findings.

Debug a bug:

Reproduce the bug first. Identify the root cause in code. Then make the
smallest fix and rerun the reproduction command.

Prepare for a commit:

Inspect the current diff, run the relevant checks, and prepare a concise commit
summary. Do not change unrelated files.

When To Stop And Restart

Start a new session when the goal changes, the old conversation is full of irrelevant context, or you want a clean review. Keep the same session when Anode needs the previous investigation to make good decisions.

Use /cancel when the current run is wrong. Use /steer when it is mostly right but needs extra direction. Use /changes before trusting the result.