Home

Go-based framework for agentic code work

foxctl

Go-based framework for agentic code work.

A Go CLI and runtime framework for code retrieval, skills, memory, context, agents, rooms, and operational workflows.

Start with foxctlBrowse docsGitHub

Start herefoxctl run code/semantic_search --input '{"format":"tree"}'

workflow preview

01OrientUse Go-backed indexers to build a ranked map before changing code.

$ foxctl run code/semantic_search --input '{"format":"tree"}'

02RetrieveIndex symbols, imports, calls, references, and files.

$ foxctl index repo build --workspace . --go --typescript --elixir

03PlanPull the exact evidence needed for a bounded implementation path.

$ foxctl run code/dag_grep --input '{"query":"buildEvidencePack"}'

04ActCoordinate persistent agents and rooms when the work needs hands.

$ foxctl agent spawn --role reviewer --exec-mode autonomous

Progress

What is current, and what is still moving

The site separates shipped behavior from plan-backed work so agents can avoid treating experimental runtime and evaluation work as production operator guidance.

CurrentDocs and deploy path

Go repo documentation, Starlight site, Cloudflare Pages deploy script, docs checks, and link checks.

CurrentRepo evidence loop

Repoindex, semantic search, DAG grep, codemaps, and CAS-backed outputs are documented as operator workflows.

CurrentAgent and room operations

Agent lifecycle, orchestration, rooms, storage, and observability have current behavior docs.

In progressDurable execution recovery

Crash recovery, idempotent side effects, and effect journal work remain tied to active plans.

In progressRefactor intelligence

Hotspot detection, confidence scoring, target selection, and slop detection are being hardened.

In progressRLM and helper runtime

LongCoT evals, helper pipelines, recursive fanout, and smolvm runtime work are still experimental.

Read progress details

Integrations

Connectors that make foxctl useful in real workflows

Integrations are grouped by status: current surfaces are safe to build on, while runtime adapter work remains explicitly marked in progress.

CurrentProviders and MCP

LLM provider detection plus MCP serving for editor and agent tool access.

Open docs

CurrentOpenAPI and plugins

Generic OpenAPI calls, auth strategies, pagination, retries, CAS output, and plugin hooks.

Open docs

CurrentHooks

Session, tool, agent, and lifecycle events wired to structured actions and safety decisions.

Open docs

CurrentChat platforms

Discord, Telegram, and Teams adapters route commands and conversation into foxctl sessions.

Open docs

CurrentObsidian bridge

Vault indexing for notes, wikilinks, aliases, tags, and retrieval-oriented memory.

Open docs

In progressSandbox and runtime adapters

OpenSandbox, RLM, durable execution, and Go-native runtime plans are still plan-backed work.

Open docs

Ways to use it

A practical loop for agentic code work

foxctl makes the repeatable path explicit: orient the agent, retrieve grounded evidence, plan with context, act through tools, then verify the result.

01Orient

Use Go-backed indexers to build a ranked map before changing code.

02Retrieve

Index symbols, imports, calls, references, and files.

03Plan

Pull the exact evidence needed for a bounded implementation path.

04Act

Coordinate persistent agents and rooms when the work needs hands.

05Verify

Keep outputs reproducible, protocol-shaped, and CI-visible.

Main surfaces

The Go-backed system pieces foxctl gives you

CLIcommandsA Go command surface for repo search, skill runs, agent control, docs refresh, and local operations.

$ foxctl ...
      |
      v
+------------------+
| command router   |
+------------------+
  | run skill
  | index repo
  | spawn agent
  | inspect docs
  v
+------------------+
| protocol result  |
| data / error     |
| meta / artifact  |
+------------------+

Ideas

• Command palette for repo work
• Scriptable local operations
• Envelope-shaped command output

Examples

• foxctl run code/semantic_search
• foxctl agent spawn
• foxctl index repo build

Read the guide

RetrievalrepoindexSemantic search, graph navigation, DAG grep, snippet extraction, and codemaps for grounded context.

question
  |
  v
+------------------+
| retrieval plan   |
+------------------+
  | semantic search
  | symbol graph
  | DAG grep
  | snippets
  v
+------------------+
| evidence pack    |
| ranked files     |
| exact anchors    |
+------------------+

Ideas

• Evidence pack before edits
• Graph-aware search
• Fallback paths for sparse queries

Examples

• semantic tree view
• DAG grep trace
• codemap generation

Read the guide

SkillsruntimeJob-tracked, ephemeral, and direct execution paths for installable tools with stable envelopes.

skill.yaml
  |
  v
+------------------+
| skill runner     |
+------------------+
  | direct call
  | queued job
  | WASI/native
  | timeout/cancel
  v
+------------------+
| stable envelope  |
| stdout summary   |
| CAS if large     |
+------------------+

Ideas

• Reusable tool contracts
• Job-tracked execution
• CAS-backed large output

Examples

• code search skill
• hook feedback skill
• OpenAPI skill

Read the guide

AgentsroomsGo-managed agent sessions plus durable room collaboration for messages, tasks, relays, and status.

agent plane              room plane
-----------              ----------
overseer                 room record
  | spawn/mail             | participants
  v                        | messages
agent sessions            | actor inbox
  | join                   | task board
  | send / inbox           | status
  +------ writes/reads --->| relay config
                           |
                           v
                   tmux | zellij | viewer

Ideas

• Overseer manages agent hierarchy
• Rooms persist collaboration state
• Relays deliver room traffic to viewers

Examples

• room create / join
• room send / inbox
• task claim / block / complete

Read the guide

StorageevidenceCAS, vectors, Turso, and Postgres keep large artifacts and working memory inspectable.

large output
  |
  v
+------------------+
| storage layer    |
+------------------+
  | CAS artifact
  | vector memory
  | Turso state
  | Postgres rows
  v
+------------------+
| inspectable ref  |
| digest / tags    |
| rebuildable idx  |
+------------------+

Ideas

• Durable evidence records
• Disposable projections
• Inspectable large artifacts

Examples

• CAS digest
• vector search
• Turso session state

Read the guide

Repo cleanup

Refactor scouts for tightening real codebases

foxctl treats cleanup as an evidence workflow: scout the shape, identify slop, tighten boundaries, and keep each refactor reviewable.

ScoutFind refactor targets before editing

Use refactor status, snapshots, hot paths, dependency expansion, and scout evidence to choose narrow cleanup targets.

foxctl refactor scout --path ./internal --language go --focus slopOpen workflow

SlopReduce AI-generated sprawl

Look for duplicated guards, repeated remapping, overgrown functions, noisy adapters, and unclear package boundaries.

foxctl refactor advisor --path ./internal --language go --focus slopOpen workflow

TightenClean repo boundaries

Tighten package placement, command surfaces, docs ownership, and runtime boundaries without broad unrelated rewrites.

foxctl refactor deps --path ./internal --language go --query Run --direction inOpen workflow

EvidenceKeep cleanup reviewable

Attach snapshots, change ranges, dependency evidence, and benchmark/doc checks so cleanup work stays auditable.

foxctl refactor evidence --artifact sha256:<digest>Open workflow

Benchmark solutions

Measured evidence for why the harness matters

The current evidence separates hot runtime cost, cold CLI startup, context size, and agent-baseline comparison so the site can make claims without hiding the tradeoffs.

1 caseContext gather speed

31.4x faster

gather_context built the RLM map evidence in 6.50s with 1.00 fact recall and a compact 1,096-character context bundle.

Review

orientationShell context reduction

85.4% less output

foxctl reduced output across command rows that actually shrank: ls, find, cat, head, tail, grep, sed, git, and go test tasks.

Review

localRepoindex and DAG paths

< 1ms fixtures

Search fallback and DAG explanation fixtures keep graph retrieval latency and allocation cost visible in the Go benchmark lane.

Review

GoHot runtime overhead

96.5ns runner

The no-hook tool runner, envelope codecs, actor lifecycle, and shell reducer hot paths are measured with allocation-aware Go benchmarks.

Review

Binary	Same task	Native output	foxctl output
ls93.8% less	List the internal package treels -la internal	483 tokens / 1,002 bytes	30 tokens / 106 bytes
find92.0% less	Find Go files under toolingfind internal/tooling -name '*.go'	825 tokens / 3,061 bytes	66 tokens / 237 bytes
cat86.6% less	Read module metadatacat go.mod	7,520 tokens / 19,723 bytes	1,011 tokens / 2,216 bytes
head14.6% less	Read the start of shell command sourcehead -n 80 cmd/foxctl/cmd/shell.go	679 tokens / 2,680 bytes	580 tokens / 2,245 bytes
tail4.9% less	Read the end of shell command sourcetail -n 80 cmd/foxctl/cmd/shell.go	655 tokens / 2,376 bytes	623 tokens / 2,245 bytes
grep98.9% less	Find Go functions in shellreducegrep -rn 'func ' internal/tooling/shellreduce	4,779 tokens / 18,632 bytes	53 tokens / 209 bytes
sed51.6% less	Read the shell command source slicesed -n '1,120p' cmd/foxctl/cmd/shell.go	1,148 tokens / 4,617 bytes	556 tokens / 2,216 bytes
git status94.9% less	Inspect worktree statusgit status --short	1,422 tokens / 5,095 bytes	72 tokens / 215 bytes
git diff89.7% less	Inspect changed-file statsgit diff --stat	1,760 tokens / 6,458 bytes	182 tokens / 503 bytes
git diff82.9% less	List changed file namesgit diff --name-only	1,313 tokens / 4,755 bytes	225 tokens / 768 bytes
git log97.3% less	Review recent commit statsgit log --stat -5	3,303 tokens / 11,464 bytes	89 tokens / 337 bytes
go test36.4% less	Run the shellreduce package testsgo test ./internal/tooling/shellreduce	22 tokens / 68 bytes	14 tokens / 41 bytes
total85.4% less	All command-output rows where foxctl reduced outputtwelve native commands, same tasks through foxctl shell reduction	23,910 tokens / 79,932 bytes	3,501 tokens / 11,338 bytes

Architecture

Canonical storage, disposable context, durable evidence

Commands return envelopes, large artifacts go to CAS, repo metadata stays rebuildable, and agent work is anchored to durable room and session records.

CLIcommands, hooks, local shells

SkillsWASI, native, job tracking

Retrievalsemantic search, repoindex, codemaps

Agentsdaemon, rooms, overseer flow

StorageTurso, Postgres, CAS, vectors

Deep links

Keep moving

QuickstartIntegrationsProgressBenchmarksRefactor scoutsProtocol v1Repoindex