Parker617/whalefall

README preview

# Whalefall 🐋

> A local **LLM agent harness**: drive any OpenAI-compatible model through built-in tools, MCP plugins, skill documents, and subagents — in a single process, with honest permissions and full trace persistence.

**Whalefall** (鲸落, "whale-fall") is a deep-sea phenomenon: when a giant whale sinks to the seabed, its body sustains an entire ecosystem of scavengers and bone-eating worms for decades. This project takes that metaphor literally — **one big language model underwrites a swarm of smaller tool calls, keeping an agent productive turn after turn**.

Inspired by the overall shape of [Claude Code](https://github.com/anthropics/claude-code), rewritten from scratch in pure Python, with every moving piece inspectable and every side-effect explicit.

---

## Highlights

- **Single-process main loop** — `LLM → tool_calls → tool_results → next turn`, fully async streaming, every chunk landed to disk via `TraceWriter`.
- **16+ built-in tools** — `read / write / edit / bash / glob / grep / web_fetch / web_search / ask / todo / notebook_edit / agent / plan_mode / skill / mcp_discover / ...`, covering the CC feature matrix with ~85% of the functionality.
- **First-class MCP support** — stdio / SSE / streamable-HTTP; plugins self-register via `@mcp.tool()`; your tools can live in a private fork without forking this repo.
- **Hierarchical skill filtering** — markdown SOP docs under `skills/`; agents pick what they can see via `allowed_skill_paths` (path prefixes with proper `/` boundary semantics).
- **Subagents** — the `agent` tool spawns a child loop with its own permissions/context/MCP subset; parent auto-summarizes child transcripts for traceability.
- **8-step permission pipeline** — hook / bypass / skip / always-allow / rule / mode / deny / prompt; explicitly-declared write tools need user approval unless bypassed.
- **BashGuard** — an `ll`-lite classifier that flags destructive `rm -rf /`, pipes to `sh`, hidden network calls, etc. before the shell sees them.
- **Triple-layer context compression** — `microcompact` (truncate old tool results), `auto_compact` (summarize after 92% of context), `precompact` (eager summary before the next turn if projected to overflow).

View full repository on GitHub →