Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

English | 简体中文

Octonoesis 🐙

CI License: MIT

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.

Octonoesis fixing a real bug end-to-end: search, diff-previewed edit, permission prompt, tests passing


Desktop app (macOS)

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.

Octonoesis desktop app: a prompt to fix failing cart tests, collapsed tool activity, the fix, and the Changes panel listing the edited file

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.


Features

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+C to 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 via LLM_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 (or OCTONOESIS.md to 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-exec for Bash, blocking ~/.ssh and credential stores.

Integration

  • MCP: stdio servers from config, tools namespaced mcp__{server}__{tool}.
  • Sub-agents: read-only child agents (Agent tool), prompt cache shared. Background agents run in detached-HEAD worktrees with SendMessage steering.
  • Background tasks: run_in_background keeps the conversation going while a command runs. Output to .octonoesis/tasks/{id}.log, notification when done.

Background bun test + sub-agent delegation + task notification, in one session


Learning Loop

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
Loading

Session 1 fails and fixes a bug and learns a rule; session 2 hits the same error class, the rule is recalled and scored a hit

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 interval

Active pool caps at 150 rules. When full, they compete on specificity × confidence × time-decay. Evidence grows unbounded; beliefs stay bounded.


Installation

Requirements:

  • Bun ≥ 1.4.0 — curl -fsSL https://bun.sh/install | bash
  • ripgrep (optional fallback if bundled @vscode/ripgrep can't run)
bun install -g octonoesis

npm / 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.

Quickstart

# 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 sandbox

Per-repo config (.octonoesis/config.json):

{
  "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" }
  ]
}

API key handling

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.


Architecture

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")]
Loading

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.


Research & Validation

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.


License

MIT — see LICENSE.

About

No description, website, or topics provided.

Resources

Contributing

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages