FFT_nano
CLAUDE.md4 starsChanged 8 months agoMITView on GitHub
Single Node.js host process: receives chat messages (Telegram/WhatsApp), runs pi (coding agent) as a subprocess, returns responses. SQLite for persistence. These subsystems close the agent's reliability/learning loops. All are additive and degrade safely.
In this repository23 other files it gives its agents.
- AGENTS.mdAGENTS.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 CLAUDE.md into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
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 23
Evaluator loop: After agent completes, evaluator.ts runs a second pi pass to score output quality.
- Distinctive: line 78
Use git stash push -u to shelve untracked files.
- Very specific: line 79
Do not commit lock files or reports/.
- Very specific: line 80
Test artifacts should be isolated to ~/fft_nano-dev, not ~/fft_nano.
- Distinctive: line 104
Before release/tag promotion:
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.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
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
FFT_nano — Project Instructions
Architecture
Single Node.js host process: receives chat messages (Telegram/WhatsApp), runs pi (coding agent) as a subprocess, returns responses. SQLite for persistence.
Message Flow
Telegram/WhatsApp → message-dispatch.ts → pi-runner.ts (spawns pi subprocess)
↓
HostEventBus (host-events.ts)
↓
telegram-streaming.ts / file-delivery.ts- Host-local delivery (preview/final):
pi-runner.tsemitsHostEvents onhostEventBus— never writes files for this path. - Cross-boundary IPC (agent-authored actions):
pisubprocess writes JSON tomessages/,tasks/,actions/,action_results/directories;startIpcWatcher()inindex.tspolls these. - Evaluator loop: After agent completes,
evaluator.tsruns a secondpipass to score output quality; verdict JSON must never leak to users (seeboundary-ipc.ts:isInternalEvaluatorVerdictText). - Cron service (
src/cron/service.ts): Drives scheduled tasks via SQLite, callsrunContainerAgentandrunEvaluatorPassdirectly. - Coding orchestrator (
src/coding-orchestrator.ts): Manages plan/execute worker routing for coding tasks; uses ephemeral worktrees and evaluator refinement loops. - Permission gate (
src/permission-gate-policy.ts): Blocks destructive bash commands for subagents or headless runs;bash-guard.tsclassifies commands. - Memory subsystem: Lexical search across transcript + document stores;
memory-backend.tsis the unified facade;memory-paths.tsowns directory layout. Optional semantic re-rank (memory-embeddings.ts) blends a local Ollama embedding cosine with the lexical score — off by default, lexical fallback always. - TUI (
src/tui/): Separate gateway server/client pair bridging the terminal UI to the host event bus over WebSocket.
Durability & Self-Improvement
These subsystems close the agent's reliability/learning loops. All are additive and degrade safely.
- Long-run durability (
src/long-run-service.ts+agent_runstable): a long run records its durable workspace asworktree_pathat start. On restart,triageActiveAgentRunsOnStartup(db.ts) marks in-flight runsinterrupted/recoverable;resumeRecoverableRuns()re-enqueues them at boot with aresume_attemptscap (FFT_NANO_LONG_RUN_MAX_RESUMES, default 2). Wired inapp.ts main()after channels are up. - Delivery outbox (
src/outbox.ts+delivery_outboxtable): at-least-once delivery with a UNIQUEdedupe_keyso a re-emitted final never double-posts. Cron announces deliver through it (cron:{id}:{run}key);flushPending()runs at startup and on every cron tick so transient outages self-heal. Interactive chat streaming is intentionally NOT routed through it (no stable dedupe key). - Self-improvement loop (
evaluator.ts→evaluator_verdictstable →coding-orchestrator.ts): evaluator verdicts are persisted;getEvaluatorStats(group)feeds the rolling pass-rate + recurring issues into each subsequent coding/subagent run. Group-scoped, coding/subagent only. - Memory injection consistency:
shouldBuildRetrievedMemoryContext(pi-runner.ts) builds retrieved-memory context for main chat and cron (isScheduledTask) and subagent (isSubagent) runs. - Skill versioning (
src/skill-history.ts): every skill mutation snapshotsSKILL.mdto.history/(bounded to 10) before overwriting; theskill_rollbackIPC action restores the prior version reversibly. - Skill self-improvement signals (
src/self-improve-signals.ts→src/skill-service.ts): a deterministic, lexicalextractLearningSignals({ userTask, agentOutput, toolExecutions })flags high-value learning (remember/correction/fail-then-fix→fullpriority;multi-step-procedure→light). Afullsignal fires the quiet skill reviewer immediately, bypassing the turn/tool counters; a per-group min-interval debounce (selfImprove.minIntervalMinutes, default 15, envFFT_NANO_SKILL_SELF_IMPROVE_MIN_INTERVAL_MINUTES) caps how often the pi subprocess spawns. Every pass — including no-ops — appends one JSONL line togroups/<group>/logs/self-improve-events.jsonl(recordSelfImproveEvent). No DB migration, no extra LLM call. - Idle skill curator (
shouldRunSkillManageridle gate +startCuratorLoopinapp.ts):state.lastInboundAtis stamped on every user-origin inbound; the curator runs only after the host has been idle forminIdleHours. An hourly unref'd loop drivesmaybeRunSkillManagervia an injectedrunCuratorTick, so curation happens independent of user traffic.minIdleHoursis now real scheduling behavior.
State Access Pattern
import { state, activeChatRuns, hostEventBus } from './app-state.js';
// Reassignable vars live on `state` object (ESM compatibility)
// Maps: activeChatRuns.get(...), activeChatRuns.set(...)Development Workflow (Authoritative)
Two-track, two-worktree model. The two worktrees share one .git; a branch can be checked out in only one at a time.
origin/main— canonical deployment line. All PRs merge here. The runtime worktree tracksmain. Direct fast-forward pushes to your own feature branch are allowed; force-push tomainis forbidden (cherry-pick or revert for rollback).origin/devis retired; merge it in or stop pushing to it.~/fft_nano-dev— edit/build/test worktree. Work on FEATURE branches here, never onmain.~/fft_nano(=/Users/username/FFT_nano, case-insensitive FS) — runtime worktree onmain; never hand-edit. Builds + restarts the launchd service.
Ship loop: feature branch in fft_nano-dev → PR to main → merge →
in ~/fft_nano: git pull --ff-only origin main → npm run build →
launchctl kickstart -k gui/$(id -u)/com.fft_nano → verify new PID + clean
logs/fft_nano.log. The service runs dist/, so a build is mandatory after
every pull. Live DB: ~/fft_nano/store/messages.db.
A drift witness (src/drift-witness-service.ts) fires at boot and on every
heartbeat. If ~/fft_nano is more than FFT_NANO_DRIFT_THRESHOLD commits
(default 4) behind main for more than 2 days, it warns in the log and enqueues
a dedupe-keyed Telegram notice (drift-witness:<local>:<remote>). Threshold
of 0 disables drift detection entirely. Set FFT_NANO_CANONICAL_BRANCH to
override main for forks / branched deployments.
- Runtime worktree (
~/fft_nano) must stay clean. Before pushing changes, verify:git status→ working tree clean (no untracked files, no modifications).- Use
git stash push -uto shelve untracked files. - Do not commit lock files or
reports/; these are excluded by.gitignore. - Test artifacts should be isolated to
~/fft_nano-dev, not~/fft_nano. - The companion runbook at
docs/ops/WORKSPACE-CLEANUP.mddocuments the one-time sweep for the historical debris — the actual cleanup remains operator-confirmed; do not auto-purge without using that runbook.
- Use
Build & Test
npm run build # TypeScript → dist/
npm run dev # Run via tsx (no build step)
npm test # All tests via node --test
npm run typecheck # Type-check without emitting
# Run a single test file
node --import tsx --test tests/<name>.test.ts
npm run format # Prettier write
npm run format:check # Prettier check (CI)
npm run validate:skills # Validate pi skill manifests
npm run doctor # Diagnose runtime envCI/CD (Required Gates)
Before release/tag promotion:
npm run release-check
npm run secret-scanGitHub Actions:
.github/workflows/release-readiness.yml: typecheck, tests, secret-scan, validate:skills, release-check.github/workflows/skills-only.yml: validate:skills for skills-only changes
Kernel surface (frozen)
Host kernel primitives are frozen in src/kernel-surface.ts / docs/KERNEL_SURFACE.md:
prompt layers, run origins, IPC kinds, workspace contract files.
Growth rule: new agent capability belongs in skills or scheduled tasks, not new host subsystems, prompt layers, run origins, or IPC envelope kinds.
Key Files
| File | Role |
src/kernel-surface.ts | Frozen kernel ABI: prompt layers, origins, IPC, workspace files |
src/index.ts | Orchestrator wiring (~2,100 lines): constructs services (longRunService, outboxDeliverer, scheduler, appRuntime) and *Deps objects |
src/app.ts | main(), startup/shutdown, connectWhatsApp; boot-time outbox flush + long-run resume |
src/app-state.ts | All global mutable state, type definitions, hostEventBus singleton |
src/message-dispatch.ts | Thin re-export; canonical dispatch lives in src/pipeline/message-dispatch-pipeline.ts (processMessage, runDirectSessionTurn) |
src/telegram-commands.ts | Telegram command handling, settings panels, callback queries |
src/pi-runner.ts | Agent subprocess spawning, runtime event emission, memory-context gate |
src/agent-runner.ts | runAgent() — workspace resolution, host-context, run lifecycle |
src/telegram-streaming.ts | Visible Telegram preview registry and completion state |
src/runtime/host-events.ts | HostEventBus — typed EventEmitter hub for host-local delivery |
src/runtime/boundary-ipc.ts | Cross-boundary envelope parsing, evaluator verdict leak guard |
src/evaluator.ts | Post-run quality scoring; verdict persistence |
src/coding-orchestrator.ts | Plan/execute worker routing; ephemeral worktrees; verdict feed-forward |
src/long-run-service.ts | Durable agent_runs; restart triage + resumeRecoverableRuns() |
src/outbox.ts | At-least-once delivery deliverer (dedupe + retry) over delivery_outbox |
src/cron/service.ts + src/task-scheduler.ts | Scheduled task engine; scheduler injects the outbox deliverer |
src/memory-backend.ts / src/memory-search.ts / src/memory-embeddings.ts | Memory facade / lexical search / opt-in semantic re-rank |
src/skill-lifecycle.ts / src/skill-history.ts | Skill IPC actions / .history versioning + rollback |
src/permission-gate-policy.ts / src/bash-guard.ts | Tool permission decisions / destructive-command classification |
src/db.ts | SQLite schema + queries; idempotent ALTER TABLE migrations at startup |
src/config.ts → src/app-config.ts | Config constants + env defaults (config.ts re-exports app-config.ts) |
Status
The index.ts decomposition (8,030 → ~2,100 lines) and the host-local EventEmitter delivery migration are complete; extracted modules use a *Deps injection pattern (buildXDeps() in index.ts, thin wrappers delegate). The Agent Durability & Self-Improvement pass (resume, outbox, evaluator feedback, cron/subagent memory, semantic memory, skill versioning) shipped and runs live on dev — see MISSION_CONTRACT.md / HANDOFF.md.
Conventions
- ESM modules (
"type": "module"); import paths use.jsextensions. - Tests in
tests/, named*.test.ts. Run after every extraction step. src/skills/andskills/contain pi skill manifests; validate withnpm run validate:skills.config/runtime.parity.jsoncontrols parity feature flags (PARITY_CONFIG).- Git hooks in
hooks/(pre-commit, pre-push) — do not bypass with--no-verify. - Semantic memory is opt-in:
MEMORY_SEMANTIC_ENABLED=1plus a local Ollama (OLLAMA_BASE_URL, defaulthttp://localhost:11434) runningMEMORY_SEMANTIC_MODEL(defaultnomic-embed-text). Tunables:MEMORY_SEMANTIC_WEIGHT,MEMORY_SEMANTIC_CANDIDATES,MEMORY_SEMANTIC_QUERY_BUDGET_MS. Absent/disabled → pure lexical.
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.

