ContextQMD
Back to Nanobot

Common Gotchas

.agent/gotchas.md

0.2.12.4 KB
Original Source

Common Gotchas

Do not use ruff format

CONTRIBUTING.md mentions ruff format, but do not run it — it destroys git blame history. Only ruff check should be used.

Config ${VAR} References

config/loader.py resolves ${VAR} patterns in config.json at load time. This is not a shell-like default-value syntax. If the environment variable is missing, load_config raises ValueError and the agent falls back to default configuration.

Example valid usage:

json
{ "providers": { "openrouter": { "apiKey": "${OPENROUTER_KEY}" } } }

Windows Compatibility

nanobot explicitly supports Windows. Key differences to keep in mind:

  • ExecTool uses cmd /c on Windows instead of sh -c (shell.py).
  • cli/commands.py forces sys.stdout/stderr to UTF-8 on startup to handle emoji and multilingual input.
  • MCP stdio server commands are normalized for Windows path separators (mcp.py).
  • Always use pathlib.Path for path manipulation; do not assume / separators.

Prompt Templates

Agent system prompts and scenario-specific instructions live in nanobot/templates/ as Jinja2 markdown files (identity.md, platform_policy.md, HEARTBEAT.md, SOUL.md, etc.). Changing these files alters agent behavior as directly as changing Python code. They are loaded by utils/prompt_templates.py.

Tool descriptions, skills, and replayed session history also shape model behavior. Treat changes to those surfaces like runtime code: keep them narrow, add a focused regression test when possible, and avoid teaching the model to repeat internal markers, local paths, or tool-call text.

Context Pollution Persists

Anything written into memory, session history, or prompt inputs can be replayed into future LLM calls. Metadata such as timestamps, local media paths, tool-call echoes, and raw fallback dumps must be bounded and sanitized before they become examples for the model to imitate.

Skills as Extension Point

Built-in skills live in nanobot/skills/ (markdown + YAML frontmatter format). Agent capabilities that are "know-how" rather than code should be added as skills, not hardcoded into the agent loop. External skills can be published to and installed from ClawHub.

Atomic Session Writes

agent/memory.py writes history.jsonl atomically (temp file + fsync + rename + directory fsync). This guarantees durability across crashes. Do not replace this with a plain open(..., "w") write.