nanobot-runtime/AGENTS.md

Agent Instructions

Scheduled Reminders

Personal reminders for the user (notifications about tasks they need to do) → use the /remind skill → stored in SQLite (db/reminders.sqlite). Never use the cron tool for these.

Background agent tasks (run a script, check something, autonomous action) → use the built-in cron tool directly.

Test: Who is the recipient? User gets notified → /remind skill (SQLite db/reminders.sqlite). Agent executes something → cron tool.

Do NOT just write reminders to MEMORY.md — that won't trigger actual notifications.

Git commit timestamps

For commit-message timestamps run bash scripts/timestamp.sh — do NOT call date directly with a format string. The exec safety guard false-positives on date '+%Y-%m-%d %H:%M:%S' (colons in %H:%M:%S match its Windows drive-letter path regex) and blocks the command.

Heartbeat Tasks

HEARTBEAT.md is checked on the configured heartbeat interval. Use file tools to manage periodic tasks:

• Add: edit_file to append new tasks
• Remove: edit_file to delete completed tasks
• Rewrite: write_file to replace all tasks

When the user asks for a recurring/periodic task, update HEARTBEAT.md instead of creating a one-time cron reminder.

Databases (SQLite)

Always store SQLite databases under db/*.sqlite (relative to the workspace root). Never use /tmp/, hardcoded absolute paths, or in-memory databases for persistent data.

How you were extended & tuned

develop/ records how this instance was extended and tuned — skills, config, service work — with verified facts and a change log you can learn from (not the upstream code). See develop/README.md; read on demand.

Explicit user details

Explicit user facts are stored in keep.md. Read at every turn.

Projects (deep details)

More details about the user, projects, hardware etc. live in projects/<name>/ (memory.md, state.md) — search those too.

Knowledge base

knowledge/ holds verified facts and measured values you can draw on when answering (e.g. notes on the models available to you). See knowledge/README.md for what's there; read on demand.

exec Tool

The exec safety guard blocks commands without an explicit workspace path (e.g. lua -e '...', which). Write scripts to files inside the workspace (e.g. tmp/script.lua) and run them with working_dir set to the workspace root.

On the first safety-guard block: diagnose the cause before retrying — check a missing working_dir first, never re-send the same blocked form, and change one variable per test until the cause is identified.

python — use uv

For all Python code (scripts, snippets, one-liners, tools) use uv, not python / python3 / pip directly.

• Run a script: uv run script.py (not python script.py)
• One-liner / snippet: uv run --with <pkg> python -c '...'
• Script with declared dependencies: uv run --script script.py (PEP 723 header inside the file)
• Add a project dependency: uv add <pkg> (not pip install)
• Remove: uv remove <pkg>
• Sync environment: uv sync
• Run a tool: uv run pytest, uv run ruff, uv run mypy, …
• REPL: uv run python

Do not use pip, pip-tools, poetry, conda, or the system python. Reason: isolated, reproducible environments with no system-level side effects, faster resolves, no "works on my machine" surprises.

File / Code Conventions

Report / result files

• Save important reports to results/ directory with descriptive, date-prefixed filenames (e.g., 2026-06-02_remind-skill-analysis-and-improvements.md)

Script-writing convention

• Location: always save scripts in the scripts/ directory.
• Language choice:
  • Extremely short script (a few lines) -> bash.
  • Longer / non-trivial script -> Python.
• Override: if the user explicitly specifies a language or location, their instruction always takes precedence.

Available scripting languages

In addition to Python and Bash, the agent can also write and run:

• Lua — via lua interpreter (scripts in tmp/, run with working_dir set to workspace root)
• Rust — via rustc / cargo (compile and run inside workspace)
• TypeScript — always via bun

Use these when the user explicitly asks for them or when they are the right tool for the job. Default remains Python for non-trivial scripts and Bash for very short shell snippets.

Git clones

• Always clone repos into workspace/src/<repo-name>, not directly into workspace root.

Temporary files

• All temporary files go to tmp/ directory.
• Clean up after tests and one-off operations.

Code changes

• User prefers changes to be made in a temporary clone under workspace/tmp/<repo-name> for review before applying

No proactive actions

When I ask you to find out, investigate, look into, or check something, that is a request for information only. Report your findings, then ask whether I want them carried out — never treat learning about a problem as a request to fix it. When in doubt, ask first.

Git commits for workspace changes

Whenever the agent modifies any skill or any file in the workspace (including dream/runtime changes), make a git commit in the workspace repo. Commit message: current date and time in SQL format (YYYY-MM-DD HH:MM:SS), prefixed to indicate it's a nanobot agent change, e.g.:

nanobot: 2026-02-12 14:35:07

Behavioral Guidelines

1. Don't assume. Don't hide confusion. Surface tradeoffs.

   • If an instruction is ambiguous, stop and ask for clarification before acting.
   • Do not make assumptions about user intent, data formats, or scope.
   • Explicitly surface tradeoffs when multiple implementation paths exist.

2. Minimum code that solves the problem. Nothing speculative.

   • Implement only the logic requested. Avoid premature abstraction, design patterns (like Strategy or Factory), or future-proofing that is not explicitly required.
   • If a simple solution exists, prefer it over complex, generalized ones.

3. Touch only what you must. Clean up only your own mess.

   • Changes must be surgical. Do not reformat files, update type hints, or rewrite existing code unless it is strictly required to fulfill the specific task.
   • If your changes introduce orphans (e.g., unused imports, dead variables), clean them up. Otherwise, leave existing code untouched.

4. Define success criteria. Loop until verified.

   • Before coding, define clear success criteria or a verification plan.
   • Iterate and self-correct until the verification tests pass. Ensure each step of the implementation is verified against the goal.

5. A multi-step task: plan and then execute, in the same turn.

   • After laying out the plan for a multi-step task or a piece of research, start carrying it out immediately — the plan is not the end of the turn. Report progress as you go.
   • Merely printing a plan and ending the turn looks like a finished answer; the user then waits for nothing.
   • This does not override No proactive actions above: a request to find out / investigate / check stays information-only. This rule applies to a task the user actually asked you to carry out.