codecuttlectl

module

v0.0.0-...-0b344dd Latest Latest Go to latest Published: Jul 20, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/codecuttle/codecuttlectl

Links

Open Source Insights

README ¶

codecuttlectl

codecuttlectl wraps foundation models with structured tool execution, diagnostic feedback loops, and conditional knowledge injection. It's the control binary for the Codecuttle meta-harness.

Early alpha. Phases 1-3 of the PoC plan are implemented. Routing engine, Optic Lobe memory, fleet telemetry, swarm orchestration, and self-evolving harness code are future work.

codecuttlectl TUI

Context

Lee et al. ("Meta-Harness: End-to-End Optimization of Model Harnesses", 2026) showed that the harness around a fixed LLM — context construction, tool orchestration, memory, state — produces a 6x performance gap on identical benchmarks. Giving an agent full access to prior execution traces enables iterative harness optimization.

We're building toward that. The Inkwell captures execution traces. The skills system ships versioned knowledge with tools. The proto contract defines a stable interface. The intent is for the system to eventually guide production of its own plugins in a versioned, iterative swarm loop.

Install

make all
sudo cp bin/codecuttlectl /usr/local/bin/codecuttlectl
sudo mkdir -p /usr/local/lib/codecuttlectl/plugins
sudo cp bin/plugins/* /usr/local/lib/codecuttlectl/plugins/
echo 'alias c3="codecuttlectl -plugin-dir /usr/local/lib/codecuttlectl/plugins"' >> ~/.bashrc

Usage

# Bedrock (default provider)
c3                              # TUI
c3 -no-tui                      # Streaming REPL
c3 -message "Fix the build"    # One-shot
c3 --session ses_abc123         # Resume
c3 --list-sessions              # Recent sessions
c3 -thinking                    # Extended reasoning

# Ollama (local models)
c3 --provider ollama --model gemma4:31b         # Explicit provider
c3 --model ollama:gemma4:31b                    # Auto-detect from prefix
c3 --provider ollama --model qwen3:32b          # Any Ollama model
c3 --provider ollama --ollama-url http://remote:11434 --model gemma4:31b  # Remote server

# Google AI (Gemini)
c3 --provider google --model gemini-2.5-pro     # Explicit provider
c3 --provider google --model gemini-2.5-flash   # Faster/cheaper
c3 --provider google --list-models              # List available models

Providers

codecuttlectl supports multiple LLM providers through a unified interface:

Provider	Flag	Models	Cost
AWS Bedrock (default)	`--provider bedrock`	Claude Opus 4.6, Sonnet, Haiku	Pay-per-token
Google AI	`--provider google`	Gemini 2.5 Pro, Flash	Pay-per-token
Ollama	`--provider ollama`	gemma4, llama3, qwen3, any local model	Free (local)

The provider is auto-detected from the model name prefix (e.g., ollama:gemma4:31b). See docs/providers.md for details.

Architecture

Named after cephalopod neurology. A cuttlefish distributes 60% of its neurons into peripheral arm clusters that solve problems locally. The software mirrors this: tool execution happens in isolated plugin subprocesses, not the central model.

Subsystem	Status
Cuttlebone Substrate — protobuf + gRPC plugin interface	Done
Inkwell — error classification + reconciliation loop	Done
Skills Registry — conditional knowledge injection	Done
Sessions — persistence, resume, Inkwell capture	Done
Typed Schema — auto-derived JSON Schema from Go structs	Done
Scaffold Generator — plugin stub generation mid-session	Done
Context Compaction — heuristic tool result summarization	Done
Multi-Provider — Bedrock + Google + Ollama via provider interface	Done
State Dictionary — ground-truth injection for local models	Done
Auto-Planning — harness-managed task extraction from text	Done
Swarm Orchestration — multi-agent routing via YAML Morphologies	Done
Swarm Backlog — parallel async delegation via Headless Agents	Done
Chromatophore Engine — Chomsky hierarchy routing	Planned
Optic Lobe — PostgreSQL + pgvector + AGE memory	Planned
Arm Nodes — edge inference agents	Planned

Tools

17 total (12 plugin, 5 built-in):

read_file write_file edit_file list_directory bash_exec grep glob git go_skills websearch webfetch github todo_manage tool_info get_skill scaffold_plugin reload_plugins

Plugins

Standalone gRPC binaries. Drop a cuttlebone-* binary in the plugin directory, discovered on next launch (or mid-session via reload_plugins). Any language. Plugins ship embedded skills (versioned Markdown) that activate based on context triggers.

Plugin inputs are defined as annotated Go structs with JSON Schema auto-derived at startup:

type myInput struct {
    Query   string        `json:"query" jsonschema:"required" jsonschema_description:"Search query"`
    Limit   types.FlexInt `json:"limit,omitempty" jsonschema_description:"Max results"`
}

// In Describe():
InputSchema: schema.MustSchema(&myInput{}),

New plugins can be scaffolded mid-session via the scaffold_plugin tool — generates a buildable stub with typed inputs, schema derivation, and proper boilerplate.

Crash recovery, execution timeouts, input validation, auto-restart. See docs/writing-plugins.md.

Sessions + Inkwell

Conversations persist to ~/.local/share/codecuttlectl/sessions/. Every tool execution recorded with timing, error classification, full I/O. The reconciler injects corrective prompts when failures are detected. Zero overhead when things work.

See docs/sessions-and-inkwell.md.

Prompt Caching & Cost Tracking

3-tier incremental extension caching for Bedrock minimizes API costs:

Tools (~12k tokens) — cached at end of toolConfig (never changes)
System prompt (~6k tokens) — cached after stable base, dynamic injections after
Messages — checkpoint on most recent message; prefix extends forward monotonically

Google AI context caching is also supported for the system prompt and tools, automatically engaging when token counts exceed the --google-cache-threshold.

The TUI status bar shows live metrics: 45.2k in 8.1k out 87% cache ~$0.42

For local models (Ollama), the status bar shows tokens and context window % without cost: 5.7k in 0.8k out 2% ctx

Session cost tracking persists across resumes. --list-sessions shows per-session cost estimates. --audit-log emits structured JSON events for external cost monitoring.

See docs/caching.md.

A background keepalive ping fires every 4 minutes during idle to prevent the 5-minute cache TTL from expiring. See caching docs for details.

Not yet implemented

Multi-model routing (Haiku/Sonnet for auxiliary tasks — design doc, PR #25 ready)
Chomsky routing (dynamic complexity classification — depends on multi-model)
Optic Lobe (cross-session semantic memory)
Work Backlog (cross-session deferred intent queue — design doc, Phase 1 done)
Fleet telemetry (OpenTelemetry — Phase 10 of streaming doc)
Self-evolving harness (outer loop from execution traces)
Proto-based schema path (cross-language plugin inputs via .proto)
MicroVM isolation (Firecracker)
Hot-reload plugins (fsnotify-based auto-discovery)
LLM-generated compaction summaries (Phase 2 — design doc, depends on multi-model)
Optic Lobe retrieval for compacted content (Phase 3 of compaction doc)

Development

make all     # Build orchestrator + all plugins
make test    # Unit tests, all packages
make proto   # Regenerate protobuf

License

See LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
codecuttlectl command codecuttlectl is the Codecuttle meta-harness CLI agent.	codecuttlectl is the Codecuttle meta-harness CLI agent.
internal
approval Package approval implements user confirmation gates for destructive operations.	Package approval implements user confirmation gates for destructive operations.
audit Package audit provides structured event logging and session-level audit trail accumulation for governance, cost attribution, and security monitoring.	Package audit provides structured event logging and session-level audit trail accumulation for governance, cost attribution, and security monitoring.
backlog Package backlog implements a persistent, cross-session intent queue for deferred work.	Package backlog implements a persistent, cross-session intent queue for deferred work.
bedrock Package bedrock provides the AWS Bedrock Converse API client for codecuttlectl.	Package bedrock provides the AWS Bedrock Converse API client for codecuttlectl.
compact Package compact implements heuristic context compaction for conversation history.	Package compact implements heuristic context compaction for conversation history.
conversation Package conversation implements the agent conversation loop with tool calling.	Package conversation implements the agent conversation loop with tool calling.
cuttlebone/v1
inkwell Package inkwell implements the diagnostic reconciliation loop for the Codecuttle meta-harness.	Package inkwell implements the diagnostic reconciliation loop for the Codecuttle meta-harness.
keyring
pluginhost Package pluginhost implements the HashiCorp go-plugin host (orchestrator side) for managing Cuttlebone tool plugins as isolated subprocesses.	Package pluginhost implements the HashiCorp go-plugin host (orchestrator side) for managing Cuttlebone tool plugins as isolated subprocesses.
pluginkit Package pluginkit provides helpers for building Cuttlebone tool plugins.	Package pluginkit provides helpers for building Cuttlebone tool plugins.
pluginkit/schema Package schema provides JSON Schema generation from Go structs and protobuf message descriptors.	Package schema provides JSON Schema generation from Go structs and protobuf message descriptors.
pluginkit/types Package types provides shared types for Cuttlebone plugin input handling.	Package types provides shared types for Cuttlebone plugin input handling.
prompt Package prompt manages embedded system prompts and dynamic template hydration.	Package prompt manages embedded system prompts and dynamic template hydration.
provider Package convert provides conversion utilities between provider-agnostic types and AWS Bedrock SDK types.	Package convert provides conversion utilities between provider-agnostic types and AWS Bedrock SDK types.
provider/bedrock Package bedrockprov wraps the existing bedrock.Client to implement the provider.Provider interface.	Package bedrockprov wraps the existing bedrock.Client to implement the provider.Provider interface.
provider/google
provider/ollama Package ollama implements the provider.Provider interface using the Ollama OpenAI-compatible HTTP API (localhost:11434/v1/).	Package ollama implements the provider.Provider interface using the Ollama OpenAI-compatible HTTP API (localhost:11434/v1/).
scaffold Package scaffold generates Cuttlebone plugin stubs from structured specifications.	Package scaffold generates Cuttlebone plugin stubs from structured specifications.
session Package session manages persistent session state for codecuttlectl conversations.	Package session manages persistent session state for codecuttlectl conversations.
skills Package skills implements the conditional skill injection system for the Codecuttle meta-harness.	Package skills implements the conditional skill injection system for the Codecuttle meta-harness.
swarm
todo Package todo manages in-memory task lists for the agent session.	Package todo manages in-memory task lists for the agent session.
tui
visualtest Package visualtest provides programmatic control of a virtual display environment for TUI visual testing.	Package visualtest provides programmatic control of a virtual display environment for TUI visual testing.
plugins
cuttlebone-bash-exec command cuttlebone-bash-exec is a Cuttlebone plugin that executes bash commands.	cuttlebone-bash-exec is a Cuttlebone plugin that executes bash commands.
cuttlebone-edit-file command cuttlebone-edit-file is a Cuttlebone plugin that performs exact string replacements in files.	cuttlebone-edit-file is a Cuttlebone plugin that performs exact string replacements in files.
cuttlebone-git command cuttlebone-git is a Cuttlebone plugin that provides git operations.	cuttlebone-git is a Cuttlebone plugin that provides git operations.
cuttlebone-github command Package github provides the GitHub REST API client and token resolution for the cuttlebone-github plugin.	Package github provides the GitHub REST API client and token resolution for the cuttlebone-github plugin.
cuttlebone-glob command cuttlebone-glob is a Cuttlebone plugin that finds files by name pattern.	cuttlebone-glob is a Cuttlebone plugin that finds files by name pattern.
cuttlebone-go-skills command cuttlebone-go-skills is a companion knowledge plugin that provides Go-specific skills, workflows, and best practices to the agent.	cuttlebone-go-skills is a companion knowledge plugin that provides Go-specific skills, workflows, and best practices to the agent.
cuttlebone-grep command cuttlebone-grep is a Cuttlebone plugin that searches file contents using regex.	cuttlebone-grep is a Cuttlebone plugin that searches file contents using regex.
cuttlebone-list-directory command cuttlebone-list-directory is a Cuttlebone plugin that lists directory contents.	cuttlebone-list-directory is a Cuttlebone plugin that lists directory contents.
cuttlebone-read-file command cuttlebone-read-file is a Cuttlebone plugin that reads file contents.	cuttlebone-read-file is a Cuttlebone plugin that reads file contents.
cuttlebone-web-fetch command cuttlebone-web-fetch is a Cuttlebone plugin that fetches URL content and converts it to readable text or markdown.	cuttlebone-web-fetch is a Cuttlebone plugin that fetches URL content and converts it to readable text or markdown.
cuttlebone-web-search command cuttlebone-web-search is a Cuttlebone plugin that provides web search and URL fetching capabilities.	cuttlebone-web-search is a Cuttlebone plugin that provides web search and URL fetching capabilities.
cuttlebone-write-file command cuttlebone-write-file is a Cuttlebone plugin that writes content to files.	cuttlebone-write-file is a Cuttlebone plugin that writes content to files.