DOCSEARCHbyAlgolia
Submit Docs

Caveman Code Documentation

repository·main·Indexed 21 days ago

https://github.com/juliusbrussee/caveman-code

A terminal-based coding agent designed to minimize token consumption through terse communication and aggressive tool-output compression. Features include an autonomous 'Ralph' loop, support for over 20 providers, and a stateful agent package (@juliusbrussee/caveman-agent) for tool execution and event streaming.

Tokens
229.9K
Snippets
635
Records
889
Agent score
72%

What's inside Caveman Code

  1. Overview of mom (Master Of Mischief)

    main

    mom (Master Of Mischief) is a self-managing Slack bot powered by an LLM. It can execute bash commands, read/write files, and interact with your development environment.

    Key characteristics include:

    • Self-Managing: It autonomously installs its own tools (via apk, npm, etc.), writes scripts, and configures credentials.
    • Slack Integration: Responds to @mentions in channels and DMs.
    • Docker Sandbox Support: Highly recommended to run mom in an isolated container for security.
    • Persistent Workspace: Maintains conversation history, files, and custom CLI tools (called "skills") in a controlled directory.
    • Thread-Based Details: Keeps main messages clean by placing verbose tool execution details in Slack threads.

  2. Overview of Caveman Code features

    main

    Caveman Code is a terminal coding agent designed to reduce token usage and costs through multi-layer compression. Key features include:

    • Caveman Mode compression: 3-layer compression of prompts, tool output, and file reads, targeting ~85% reduction in tool output tokens.
    • Multi-provider support: Supports 20+ providers and 6 OAuth flows (e.g., Claude Pro, ChatGPT Plus, GitHub Copilot, Gemini) to use existing subscriptions.
    • Session management: Supports session branching (forking at any turn) and auto-saves JSONL sessions per current working directory (cwd).
    • Plan mode & Subagents: Features read-only exploration and structured planning, followed by up to 7 parallel, worktree-isolated subagents for execution.
    • Native Sandboxing: Uses macOS Seatbelt, Linux Landlock, or Windows Restricted Tokens. Permission modes can be cycled using Shift+Tab.
    • MCP Integration: Supports stdio, Streamable HTTP, and in-process Model Context Protocol (MCP). caveman-code can also function as an MCP server.
    • Hooks: Compatible with Claude Code's settings.json schema, supporting 12 lifecycle events.
    • Memory: Integrates with cavemem for episodic-to-semantic consolidation and bridges Claude Code's MEMORY.md.

  3. Understand the documentation structure

    main

    The documentation is organized into several key areas:

    • Quickstart & Setup: Found in getting-started/ (includes Install, Auth, and Models).
    • Technical Reference: Found in reference/ (covers Tools, Slash Commands, Skills, Subagents, Memory, MCP, Hooks, Permissions, Plan Mode, Daemon, and Recipes).
    • Migration Guides: Found in migration/ (guides for moving from Claude Code, Codex, or Aider).
    • API Reference: Found in api.md (covers SDK, JSON-RPC, OpenAPI, and the extension API).
    • Recipes & Troubleshooting: Found in cookbook.md and troubleshooting.md respectively.
    • LLM Context: The public/llms.txt file provides an LLM-friendly entry point.

  4. Summary of Validation-First Principles

    main

    The Validation-First approach is built on these core tenets:

    • Automated Verification: If an agent cannot validate a requirement, it is not considered met.
    • The 6-Gate Pipeline: Compilation $\rightarrow$ Unit Verification $\rightarrow$ Integration $\rightarrow$ Benchmarks $\rightarrow$ Smoke Test $\rightarrow$ Manual Audit.
    • Cost-Effective Validation: Catch problems at the build stage (cheap) rather than at launch (expensive).
    • Requirement Mapping: Every spec requirement must map to at least one validation gate.
    • Phase Control: Use phase gates to control transitions between Hunt phases.
    • Regression is P0: Stop all new feature work to fix regressions immediately.

  5. Use @juliusbrussee/caveman-markdown-preview for rendering

    main

    The @juliusbrussee/caveman-markdown-preview extension provides the following rendering capabilities:

    • Terminal View: Renders markdown into a paginated, styled view directly in your terminal.
    • HTML Export: Exports the rendered output to a single-file HTML page using headless Chrome.
    • PDF Export: Exports the rendered output to a PDF file via headless Chrome.
    • Math Support: Handles LaTeX math equations using KaTeX.

  8. What is DESIGN.md and how does it function?

    main

    A DESIGN.md file serves as the visual specification layer for a project. It is a parallel constraint layer that defines the project's visual language—colors, typography, spacing, components, and responsive behavior—in a format specifically optimized for AI agents to read and apply consistently.

    It is distinct from other project documents:

    • CLAUDE.md: Defines how to build the project (coding instructions).
    • Kits: Defines what must be true (behavioral constraints).
    • DESIGN.md: Defines what it looks like (visual constraints).
    • Plans: Defines how to build it (task breakdown).

    Use DESIGN.md when defining or revising visual identity, importing a third-party design system, or auditing UI code against design tokens.

  9. What is Cavekit Revision and why use it?

    main

    Revision is the process of tracing production defects (bugs) upstream through the Cavekit chain to find the gap in requirements or prompts that allowed the defect to occur.

    Instead of just patching code, you fix the source (the kits and prompts). This ensures that the iteration loop can reproduce the fix autonomously in future runs, preventing the bug from being re-introduced when the system regenerates code.

    Key Benefits:

    • Persistence: Bug fixes become permanent cavekit improvements.
    • Self-Correction: The iteration loop learns from manual interventions.
    • Monotonic Progress: The gap between what kits describe and what actually works continuously shrinks.

  10. Overview of the Token Efficiency Initiative

    main

    The Token Efficiency Initiative is a design strategy adopted by Caveman Code to reduce token consumption (specifically for SWE-bench tasks) without sacrificing performance. It achieves this through several core architectural mechanisms:

    • Layered Cache Policy: Implementing cache breakpoints to avoid re-sending redundant system, tool, and project context.
    • Deterministic Model Routing: Routing tasks to different models based on complexity (e.g., using cheaper models for edit/verify tiers).
    • Repomap with PageRank: Using a specialized repository map to provide efficient context.
    • Shadow-git Checkpoints: Utilizing git-based state management for sessions.
    • Executable Verifier Loop: A feedback loop to ensure correctness while minimizing unnecessary tool calls.

    This initiative is implemented via a collection of specialized modules called cavekits.

  12. How Extension UI works in RPC Mode

    main

    In RPC mode, extensions interact with the user via a request/response sub-protocol on top of the standard command/event flow. Methods are split into two categories:

    1. Dialog Methods (Blocking)

    These methods emit an extension_ui_request on stdout and block the extension until the client sends an extension_ui_response on stdin with a matching id.

    • select: User chooses from a list.
    • confirm: Yes/No confirmation.
    • input: Free-form text input.
    • editor: Multi-line text editor.

    Note: If a timeout is provided, the agent auto-resolves with undefined (for dialogs) or false (for confirm) if the client does not respond.

    2. Fire-and-Forget Methods (Non-blocking)

    These emit an extension_ui_request on stdout but do not expect a response. The client can display the info or ignore it.

    • notify: Display a notification (info, warning, or error).
    • setStatus: Update the status bar/footer.
    • setWidget: Display a block of text lines (aboveEditor or belowEditor).
    • setTitle: Set the terminal/tab title.
    • set_editor_text: Set the text in the input editor.