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. Manage periodic tasks there with file tools (edit_file / write_file), not via one-time cron reminders.

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.

Workspace stores

• develop/ — how this instance was extended and tuned (see develop/README.md); read on demand
• keep.md — explicit user facts; read at every turn
• projects/<name>/ — deep details about the user, projects, hardware; search those too
• knowledge/ — verified facts and measured values (see knowledge/README.md); 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.

Never put prose or user-supplied text into a command string — not as an argument, not in a heredoc, not through a pipe. The guard scans the raw command string and has no shell parser, so quoting does not help. Any X: where X is an ASCII letter not preceded by another ASCII letter parses as a Windows drive path and blocks the whole command: Czech Cíl:, Závěr:, směr: all trip it (the diacritic before the letter defeats the guard's ASCII-only lookbehind), and so does date '+%H:%M:%S'. A literal ../ anywhere in the command — even inside prose — trips the traversal guard too.

Instead: write_file the text to tmp/, then pass the path (--file tmp/x.md, or < tmp/x.md). A path in the command is safe, and file tools are not subject to this guard. Skill CLIs that take text follow this — see skills/project and skills/note.

python — use uv

For all Python code use uv, never python / python3 / pip / poetry / conda directly. Details in skills/python/SKILL.md.

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

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.