English | 简体中文
A terminal coding agent that learns from its own mistakes.
Octonoesis reads code, edits files, runs tests, connects to MCP servers, and delegates to sub-agents. The difference is what happens after. Every tool call goes into an append-only journal. Failures get fingerprinted. A state machine segments them into fail→fix→verify episodes, and an LLM distiller turns those into rules — plain markdown files you can read, edit, or delete. Next time the same kind of error comes up, the relevant rules get injected into context. Confidence is earned by evidence (the failing command passes again), not model self-assessment.
TypeScript on Bun, Ink TUI, with Noe — an eight-tendrilled mascot whose third eye breathes while it thinks. One design rule: the LLM interprets, the harness authorizes.
The same engine also runs in a native macOS app. Each session is its own engine process. You can run several sessions side by side, check what changed in a per-file diff panel, rewind files to any checkpoint, and look through the rule pool the learning loop has built.
Download Octonoesis-macos-arm64.dmg from Releases and drag the app to Applications. On first launch it unpacks itself; click Close, and open it again if it does not start on its own. Bun is not required, because the app bundles its own runtime and the engine. Add a provider key under Provider settings; it is stored in the macOS Keychain.
The app is not notarized yet. The first time you open it, macOS will block it; go to System Settings → Privacy & Security and click Open Anyway. You can also clear the quarantine flag instead: xattr -dr com.apple.quarantine /Applications/Octonoesis.app.
To build it from source, see desktop/README.md.
Core
- 7 built-in tools (Read, Glob, Grep, Edit, Write, Bash, TodoWrite). Zod-validated, serial execution, repo-root confined.
- Interactive TUI and one-shot CLI. Streaming markdown output.
Ctrl+Cto cancel. Retries on 429/5xx with backoff. - One line per tool call with a result summary —
✓ Read src/user.ts · 42 lines,✗ Bash bun test · exit 1— plus the learning loop shown inline (see below). Input and status line stay pinned to the bottom; resizing reflows the whole session cleanly. - Permission prompt on every mutation —
[y] once / [n] no / [a] always— with diff preview for edits. - Spark-X2.6 by default with thinking disabled; Claude via
LLM_PROVIDER=anthropic, or any OpenAI-compatible endpoint viaLLM_PROVIDER=openai.
Context & memory
- Auto-compaction near the context limit (forked summarizer), so 20+ turn sessions work fine.
- Long-term memory: facts extracted at session end into
.octonoesis/memory/, recalled per query. - Project instructions from
CLAUDE.md(orOCTONOESIS.mdto override). - Status line shows model, cost, context %, tokens. Stats logged to
.octonoesis/stats.jsonl.
Learning loop — details below
Extensibility
- Skills: drop a markdown file in
.octonoesis/skills/, call it as/my-skill. - Hooks: shell commands on 6 lifecycle events, time-budgeted.
- Config: one file (
.octonoesis/config.json) for model, MCP servers, hooks, permissions, sandbox. Cloned repos can't run foreign hooks/servers until you opt in. - macOS sandbox: opt-in
sandbox-execfor Bash, blocking~/.sshand credential stores.
Integration
- MCP: stdio servers from config, tools namespaced
mcp__{server}__{tool}. - Sub-agents: read-only child agents (
Agenttool), prompt cache shared. Background agents run in detached-HEAD worktrees withSendMessagesteering. - Background tasks:
run_in_backgroundkeeps the conversation going while a command runs. Output to.octonoesis/tasks/{id}.log, notification when done.
Tool calls are journaled with three-level error fingerprints (tool|error_class, +file, +expression). A state machine segments the journal into fail→fix→verify episodes. At the end of each query, an LLM distiller turns new episodes into rules — one markdown file each. On the next matching failure, the best rules (max 2) get injected with the tool output; broad, proven rules are also loaded at session start.
A rule earns confidence only when the command that originally failed passes again. Bayesian Beta posteriors — never model self-assessment.
flowchart LR
O["OBSERVE\nBash fails → fingerprint"] --> M["MATCH\nSearch rules by signature\n(fine → medium → coarse)"]
M --> I["INJECT\nAppend advice as\nocto-memory block"]
I --> F["FIX\nAgent edits source"]
F --> V["VERIFY\nRe-run command\nhit or miss"]
V --> L["LEARN\nSegment episodes,\ncalibrate α/β, rebuild"]
L -->|"rules available for next failure"| M
The loop is visible in the transcript — only when something actually happens:
✗ Bash bun test · exit 1
↳ recalled rule-undefined-property-access-runtime · 0.60
✓ Edit src/buggy.ts · +4 −4 lines
✓ Bash bun test · exit 0
↳ rule-undefined-property-access-runtime hit · 0.60 → 0.67
✻ strengthened 1 rule
A rule is just a file:
---
id: rule-undefined-property-access-runtime
triggers:
tools: [Bash]
command_prefix: [bun test]
error_signatures:
- bun-test|TypeError
- bun-test|TypeError|src/buggy.ts
- bun-test|TypeError|src/buggy.ts|evaluating user.name
alpha: 5
beta: 2
confidence: 0.7143
evidence: [ep_0001, ep_0002]
status: active
---
When `bun test` fails with a TypeError on property access of a potentially null object,
add optional chaining (`?.`) and a nullish coalescing fallback (`?? defaultValue`).
Check the call site — the caller may be passing `null` where a valid object is expected.ls .octonoesis/rules/ # every rule is a file
octonoesis rebuild-rules --force # regenerate every rule from episodes.jsonl
octonoesis --stats # per-bucket Beta posterior + 95% credible intervalActive pool caps at 150 rules. When full, they compete on specificity × confidence × time-decay. Evidence grows unbounded; beliefs stay bounded.
Requirements:
- Bun ≥ 1.4.0 —
curl -fsSL https://bun.sh/install | bash - ripgrep (optional fallback if bundled
@vscode/ripgrepcan't run)
bun install -g octonoesisnpm / npx work too:
npm install -g octonoesis
npx octonoesis "Fix the failing test in src/user.ts"Bun is a runtime dependency, not just a build tool. The package is a Bun bundle (#!/usr/bin/env bun) that won't run under Node — bun needs to be on your PATH even when installed via npm. For a zero-dependency option, grab a standalone binary from Releases.
For browser-downloaded macOS binaries, run xattr -d com.apple.quarantine <file> before the first run.
# Spark (default; thinking disabled)
export SPARK_API_KEY="ak-..."
# Or Anthropic
export LLM_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="sk-..."
# ...or any OpenAI-compatible endpoint
export LLM_PROVIDER="openai"
export OPENAI_API_KEY="sk-..."
# export OPENAI_BASE_URL="https://api.deepseek.com"octonoesis # interactive TUI
octonoesis "Fix the failing test in src/user.ts" # one-shot
octonoesis --sandbox "run the build" # Bash in macOS sandboxPer-repo config (.octonoesis/config.json):
At startup, Octonoesis captures API keys in module memory and clears them from process.env. Subprocesses don't get keys by default — set OCTONOESIS_INHERIT_API_KEYS=1 to opt in. Fork children (compaction, memory, sub-agents) do get keys since they call the model.
Keys exported by your shell are still visible to same-user processes via OS inspection. Put keys in the repo .env instead — Bun loads it directly. The permission prompt on every shell command is the operative security boundary.
flowchart TD
IN["CLI one-shot / Ink TUI"] --> CTX["Context assembly\nCLAUDE.md · memories · rules · skill catalog · MCP tools"]
CTX --> Q{"context near limit?"}
Q -- yes --> CP["auto-compact\n(forked summarizer)"] --> LLM
Q -- no --> LLM["LLM stream"]
LLM -- text --> UI["streamed to terminal"]
LLM -- tool_use --> PERM["permission prompt\n(y/n/a + diff preview)"]
PERM --> EXEC["tool executes\nsandboxed Bash · MCP proxy · sub-agent · background task"]
EXEC --> HOOKS["hooks fire · failures fingerprinted\n→ matching rules injected"]
HOOKS --> LLM
LLM -- "no tool calls" --> DONE["final answer · memory extraction · stats"]
EXEC -. every event .-> J[("journal.jsonl\nappend-only ledger")]
Three layers: the journal is the source of truth (append-only, never edited). Episodes, rules, and calibration are derived views — rebuildable from the journal. The context compiler assembles per-task packets under token budgets, split into cache-stable system prompt and volatile preamble.
The learning loop's claims are measured, not asserted. Null and negative results included.
- 150-fixture validation: 15 error scenarios, 7 fingerprint buckets, 24 negative-control runs.
- Cross-model transfer: a rule from Claude Haiku lifted gpt-4o-mini from 2/20 to 20/20 on unseen instances (McNemar p<0.001, pre-registered, negative control null).
- Self-loop: weak model teaching itself reached 11/20 from 2/20 — real but bounded by distiller quality.
- One negative finding (RepoQuirk) and one methodology lesson (weak-model probes) reported as-is.
Full data: reports.md.
MIT — see LICENSE.




{ "model": "claude-sonnet-4-6", "maxTurns": 30, "sandbox": { "enabled": true }, "mcpServers": { "fs": { "command": "bunx", "args": ["--bun", "@modelcontextprotocol/server-filesystem", "/data"] } }, "hooks": [ { "event": "post_tool_use", "toolPattern": "Bash", "command": "jq -r .outcome >> .hook-log" } ] }