FFT_nano
AGENTS.md4 starsChanged 8 months agoMITView on GitHub
This repo is FFT_nano: an autonomous AI coworker host. One Node.js process receives Telegram/WhatsApp messages, stores state in SQLite, runs the pi coding-agent subprocess (Docker when healthy, else host runtime), and streams answers back to the chat. The same process also serves a terminal UI (WebSocket 127.0.0.1:28989), a Web Control Center (127.0.0.1:28990), and an ACP v1 stdio surface (dist/acp-stdio.js). TypeScript, ESM everywhere ("type": "module"). Node >= 20. Release gates (required before tag/promotion): CI (.github/workflows/): release-readiness.yml on PR/push to main; skills-only.yml…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-telegramSkill
- add-telegram-swarmSkill
- agent-browserSkill
- agent-harness-engineerSkill
- autoresearch-createSkill
- autoresearch-finalizeSkill
- fft-coder-opsSkill
- fft-dashboard-opsSkill
- fft-debugSkill
- fft-farm-bootstrapSkill
- fft-farm-onboardingSkill
- fft-farm-opsSkill
- fft-host-ipcSkill
- fft-setupSkill
- fft-telegram-opsSkill
- loopsSkill
- rapid-researchSkill
- skill-mechanicSkill
- web-searchSkill
- customizeSkill
- debugSkill
- setupSkill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 58
Evaluator loop: after a run, evaluator.ts launches a second pi pass to score output quality.
- Distinctive: line 143
When spawning subagents, prefer small/cheap models whenever possible.
- Distinctive: line 151
All additive; every piece degrades safely when disabled.
- Very specific: line 193
Never run a second foreground host next to the installed service.
- Very specific: line 255
Keep groups/main/ empty in-repo.
- Distinctive: line 258
Keep one reusable general-purpose dev worktree at most.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
FFT_nano / NanoClaw Agent Notes
This repo is FFT_nano: an autonomous AI coworker host. One Node.js process
receives Telegram/WhatsApp messages, stores state in SQLite, runs the pi
coding-agent subprocess (Docker when healthy, else host runtime), and streams
answers back to the chat. The same process also serves a terminal UI
(WebSocket 127.0.0.1:28989), a Web Control Center (127.0.0.1:28990), and an
ACP v1 stdio surface (dist/acp-stdio.js).
TypeScript, ESM everywhere ("type": "module"). Node >= 20.
Build, Test, Validate
npm run build # tsc -> dist/ AND web UI -> dist-web/ (service runs dist/)
npm run typecheck # tsc --noEmit
npm test # all tests: node --import tsx --test
node --import tsx --test tests/foo.test.ts # run ONE test file
npm run format # prettier write (src/**/*.ts); format:check for CI
npm run validate:skills # skill frontmatter/structure (repo + personal layers)
npm run doctor # runtime health diagnosticsRelease gates (required before tag/promotion):
npm run release-check # validate:skills, typecheck, tests, secret-scan, pack-check
npm run secret-scan # no personal paths, chat ids, secrets
git diff --check # no merge markers
git status --short # clean candidateCI (.github/workflows/): release-readiness.yml on PR/push to main;
skills-only.yml validates skills alone.
Architecture
Telegram/WhatsApp
-> src/pipeline/message-dispatch-pipeline.ts (processMessage, runDirectSessionTurn)
-> src/pi-runner.ts spawn pi subprocess (sandbox: docker/bwrap/host)
| emits HostEvent on src/runtime/host-events.ts (HostEventBus)
v
telegram-streaming.ts / file-delivery.ts / TUI / Web Control Center
Cross-boundary IPC: the pi subprocess writes JSON envelopes into
data/ipc/<group>/{messages,tasks,actions,action_results,deliver_files};
the host polls them (IPC watcher in src/host-coordination.ts).Key facts:
src/index.tsis a 3-line shim; real composition lives insrc/wiring.ts(channels, routing, admin command policy, service construction). Extracted modules take a*Depsobject (buildXDeps()inwiring.ts).- Global mutable state sits on
src/app-state.ts:state,activeChatRuns, and thehostEventBussingleton. Reassignable vars live on thestateobject for ESM compatibility. - Evaluator loop: after a run,
evaluator.tslaunches a second pi pass to score output quality. Verdict JSON must never reach users; guard:runtime/boundary-ipc.ts(isInternalEvaluatorVerdictText). - Cron service (
src/cron/service.ts+task-scheduler.ts): scheduled tasks via SQLite; scheduler modev2default. - Coding orchestrator (
coding-orchestrator.ts): plan/execute worker routing, ephemeral worktrees, verdict feed-forward. - Persistence:
src/db.tsowns schema + queries; idempotentALTER TABLEmigrations run at startup. Live DB:<runtime checkout>/store/messages.db.
State access pattern:
import { state, activeChatRuns, hostEventBus } from './app-state.js';Frozen kernel surface
src/kernel-surface.ts and docs/KERNEL_SURFACE.md define the frozen ABI:
| Surface | Values |
| Prompt layers | stable, session_bootstrap, ephemeral |
| Prompt modes | full, minimal, maintenance |
| Run origins | interactive-main, subagent, headless, evaluator, maintenance |
| IPC envelope kinds | message, task, action, action_result (+ dir deliver_files) |
| IPC payload types | run_progress, pause_task, resume_task, cancel_task, refresh_groups, register_group, memory_action, skill_action, subagent_action, farm_action, schedule_task |
| Workspace contract files | NANO.md, SOUL.md, TODOS.md, HEARTBEAT.md, BOOT.md, BOOTSTRAP.md, MEMORY.md |
Growth rule: new agent capability belongs in skills (skills/runtime/)
or scheduled tasks, not in new prompt layers, run origins, IPC kinds, or
contract filenames. Layer roles: stable = identity/safety + SOUL.md only
(cacheable prefix); session_bootstrap = NANO.md, MEMORY.md, skill
catalog (fresh sessions); ephemeral = inbound metadata, TODOS.md,
HEARTBEAT.md, retrieved memory (every turn).
Skills system
Layers merged each run into the agent home
(data/pi/<group>/.pi/skills/, mounted at /home/node/.pi/skills):
skills/runtime/: repo-tracked agent skills (source of record).skills/setup/: NOT agent skills. Human operator guides only.~/nano/skills/: personal, untracked. Wins name collisions on main-chat runs. Non-main group runs receive repo skills only.
Sync prunes only skills recorded in .fft_nano_managed_skills.json; manually
installed skills survive. Mutations snapshot SKILL.md to .history/
(src/skill-history.ts); the skill_rollback IPC action restores prior
versions. Validate with npm run validate:skills.
Memory protocol
- Canonical memory: per-group
groups/<group>/MEMORY.md(+memory/), globalgroups/global/MEMORY.md. SOUL.mdis identity/policy context. Never use it as a compaction log.- Lexical search across transcripts + documents via the
memory-backend.tsfacade;memory-paths.tsowns layout. Opt-in semantic re-rank:MEMORY_SEMANTIC_ENABLED=1plus local Ollama (nomic-embed-textdefault). Absent/disabled means pure lexical fallback. - Retrieved-memory context is built for main chat, cron (
isScheduledTask), and subagent (isSubagent) runs alike (shouldBuildRetrievedMemoryContextinpi-runner.ts).
Optional env for farm profile flows (FFT_PROFILE=farm):
FARM_MODE=demo|productionFARM_PROFILE_PATH(defaults todata/farm-profile.json)FARM_STATE_ENABLED=trueHA_URL,HA_TOKENFFT_DASHBOARD_REPO_PATH
Channels and access control
- Main chat answers everything. Other chats need the trigger prefix
@<ASSISTANT_NAME>(default:FarmFriendunderFFT_PROFILE=farm, elsefft_nano; override withASSISTANT_NAME). - Claim main:
/id, then/main <secret>usingTELEGRAM_ADMIN_SECRET, or setTELEGRAM_MAIN_CHAT_IDand restart./gateway status|restartis main-admin only. - Coder delegation:
/coder <task>executes;/coder-plan <task>plans only (aliases/coding, "use coding agent"). Main/admin chat only. Natural- language coding requests stay with the main assistant unless the operator approves escalation; approval controls offer Plan / Execute / Cancel. Execute-mode runs use a host-managed isolated worktree and report the worktree path, changed files, and test commands. - When spawning subagents, prefer small/cheap models whenever possible; use a larger model only when the task clearly needs it.
- Per-chat delivery modes (
/delivery):stream,append,off,draft; seedocs/TELEGRAM_DELIVERY.md. Interactive streaming is intentionally NOT routed through the delivery outbox.
Durability and self-improvement subsystems
All additive; every piece degrades safely when disabled.
- Long-run durability (
long-run-service.ts,agent_runstable): runs record their durable workspace asworktree_path. On boot,triageActiveAgentRunsOnStartupmarks in-flight runs interrupted or recoverable;resumeRecoverableRuns()re-enqueues them, capped byFFT_NANO_LONG_RUN_MAX_RESUMES(default 2). - Delivery outbox (
outbox.ts,delivery_outbox): at-least-once finals with UNIQUEdedupe_keyso re-emitted finals never double-post. Cron keys look likecron:{id}:{run}.flushPending()runs at startup and each cron tick. Interactive chat bypasses it (no stable dedupe key). - Evaluator feed-forward: verdicts persist to
evaluator_verdicts;getEvaluatorStats(group)injects rolling pass-rate + recurring issues into later coding/subagent runs. Group-scoped. - Skill self-improvement signals (
self-improve-signals.ts->skill-service.ts): deterministic lexical signals (remember,correction,fail-then-fixfire the quiet reviewer immediately withfullpriority;multi-step-procedureislight). Debounced per group byselfImprove.minIntervalMinutes(15; envFFT_NANO_SKILL_SELF_IMPROVE_MIN_INTERVAL_MINUTES). Every pass appends one JSONL line togroups/<group>/logs/self-improve-events.jsonl. - Idle skill curator:
state.lastInboundAtstamps user-origin inbound messages; curation waits forminIdleHoursidle; an hourly unref'd loop drivesmaybeRunSkillManager. - Drift witness (
drift-witness-service.ts): warns when the runtime checkout lags canonicalmainby more thanFFT_NANO_DRIFT_THRESHOLDcommits (default 4) for more than 2 days.0disables. SetFFT_NANO_CANONICAL_BRANCHfor forks.
Runtime and service model
Three ways to run; they are not interchangeable:
./scripts/start.sh start/npm start: foreground production-style run../scripts/start.sh dev/npm run dev: tsx source-level debugging../scripts/service.sh <install|uninstall|start|stop|restart|status|logs>: the OS service. macOS: LaunchAgentcom.fft_nano. Linux: systemdfft-nano. Android/Termux: termux-servicesfft-nano(first-class daemon target; enable autostart once withsv-enable fft-nano).
Operating rules:
- Never run a second foreground host next to the installed service. A
singleton lock (
data/fft_nano.lock) blocks double hosts; violations show up as Telegram polling conflicts. - The service runs
dist/. After every pull or code change:npm run build, then restart (launchctl kickstart -k gui/$(id -u)/com.fft_nanoon macOS). Verify a new PID and a cleanlogs/fft_nano.log; check listeners withlsof -nP -iTCP:28989 -sTCP:LISTENand port28990. - The web UI serves gitignored
dist-web/control-center/;git pullalone never updates it. Rebuild + restart required. - Debugging env:
LOG_LEVEL=debug(container args/mounts, verbose container logs),FFT_NANO_DRY_RUN=1(routing smoke test, no LLM calls). Group logs:groups/<group>/logs/. Docker disk failures:./scripts/docker-recover.sh. - Provider config flows through
.envinto the container passthrough allowlist:PI_API,PI_MODEL, provider keys. Wrong combos produce "No models available" / "Model not found". - Feature flags beyond env vars live in
config/runtime.parity.json.
Workspace bootstrap and heartbeat
- Main workspace maps to
~/nanoby default (FFT_NANO_MAIN_WORKSPACE_DIRoverrides). The host auto-seeds missing contract files from the kernel list above; optional startup ritualBOOT.mdis seeded when enabled (FFT_NANO_WORKSPACE_ENABLE_BOOT_MD=1). - Fresh installs get a host-enforced bootstrap interview while
BOOTSTRAP.mdis pending: normal tasks redirect into the interview and/coderis blocked. Completion token:ONBOARDING_COMPLETE. Gates:FFT_NANO_WORKSPACE_ENFORCE_BOOTSTRAP_GATE[_EXISTING]. - Heartbeat runs a main-session check against
HEARTBEAT.md, default every 4h (FFT_NANO_HEARTBEAT_EVERY). Effectively empty checklist files are skipped. OK-only heartbeats post "heartbeat okay" unlessFFT_NANO_HEARTBEAT_SHOW_OK=0. Ack length gate:FFT_NANO_HEARTBEAT_ACK_MAX_CHARS(300). Optional activity window:FFT_NANO_HEARTBEAT_ACTIVE_HOURS(HH:MM-HH:MMorMon-Fri@HH:MM-HH:MM).
Development workflow (two worktrees, one git)
The dev and runtime worktrees share one .git; a branch can be checked out
in only one at a time.
origin/mainis the canonical deployment line. All promotion goes through PRs. Direct fast-forward pushes to your own feature branch are allowed. Force-push tomainis forbidden (cherry-pick or revert instead).origin/devis retired.~/fft_nano-dev(this checkout): edit/build/test on FEATURE branches. Do not commit here onmain.~/fft_nano: runtime checkout pinned tomain. Never hand-edit. Builds and restarts the installed service.
Ship loop:
- Feature branch in
~/fft_nano-dev, push, open PR tomain, merge. - In
~/fft_nano:git pull --ff-only origin main. npm run build(mandatory; the service runsdist/).- Restart the service; verify new PID + clean log.
Hygiene:
- The runtime checkout must stay clean. Shelve strays with
git stash push -u. Isolate test artifacts in the dev checkout. Never commit lock files orreports/(already gitignored). - Keep
groups/main/empty in-repo; treat any in-repo workspace usage as local-only and never commit personal memory/state. - Hooks in
hooks/(pre-commit, pre-push): do not bypass with--no-verify. - Keep one reusable general-purpose dev worktree at most. Reuse it only for work on the same branch; otherwise finish, checkpoint, or remove it. Never delete a worktree holding unreviewed changes.
- Feature worktrees may run temporary validation, but stop the installed
service first to avoid channel conflicts; restore root-
mainruntime after. - Fresh-install releases must be proven on the scripted install path
(
README.md,docs/ONBOARDING.md,scripts/setup.sh,scripts/onboard-all.sh,.env.example,scripts/service.sh), not just as an upgrade of an existing machine.
Scoped-pass pattern
Big changes follow MISSION_CONTRACT.md conventions and hand off via
HANDOFF.md (keep it current after major milestones). Acceptance per pass:
typecheck clean, npm test green, behavior covered by a unit test that fails
before the change, no new user-visible surface.
Key files
| File | Role |
src/kernel-surface.ts | Frozen kernel ABI (see docs/KERNEL_SURFACE.md) |
src/index.ts | Thin entrypoint; calls main() in wiring.ts |
src/wiring.ts | Host composition: channels, routing, admin command policy |
src/app-state.ts | Global mutable state + hostEventBus singleton |
src/pipeline/message-dispatch-pipeline.ts | Canonical dispatch pipeline |
src/pi-runner.ts | Pi subprocess spawning, sandbox wiring, runtime events, memory-context gate |
src/agent-runner.ts | runAgent(): workspace resolution, host-context, run lifecycle |
src/host-coordination.ts | Host↔agent coordination, IPC watcher |
src/runtime/host-events.ts / src/runtime/boundary-ipc.ts | Typed event hub / envelope parsing + leak guards |
src/db.ts | SQLite schema + queries + idempotent migrations |
src/config.ts -> src/app-config.ts | Config constants and env defaults |
src/evaluator.ts / src/coding-orchestrator.ts | Quality scoring / plan-execute routing |
src/cron/service.ts + src/task-scheduler.ts | Scheduled task engine |
src/outbox.ts / src/long-run-service.ts | At-least-once delivery / durable run resume |
src/memory-backend.ts, memory-search.ts, memory-embeddings.ts | Memory facade / lexical search / semantic re-rank |
src/skill-lifecycle.ts / src/skill-history.ts | Skill IPC actions / versioning + rollback |
src/permission-gate-policy.ts / src/bash-guard.ts | Tool permission decisions / destructive-command classification |
src/tui/ | Terminal UI gateway server/client bridging to the host bus |
web/control-center/ | React control center, built into dist-web/ |
Conventions
- Relative imports end with
.js. - Tests live in
tests/*.test.ts(node:test through tsx). Run the relevant test files after each change; the whole suite before PRs. - Skill manifests validate with
npm run validate:skills. - Official distribution is GitHub Releases; npm publish is deferred.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

