Agentops compile

install

source · Clone the upstream repo

git clone https://github.com/boshu2/agentops

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/boshu2/agentops "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/compile" ~/.claude/skills/boshu2-agentops-compile-9f033f && rm -rf "$T"

manifest: skills/compile/SKILL.md

Compile — Knowledge Compiler

Reads raw

.agents/

artifacts and compiles them into a structured, interlinked markdown wiki. Inspired by Karpathy's LLM Knowledge Bases.

What This Skill Does

The knowledge flywheel captures signal reactively (via

/retro

/post-mortem

/forge

/compile

closes the loop by:

Mining unextracted signal from git and
```
.agents/
```
(existing)
Growing learnings via validation, synthesis, and gap detection (existing)
Compiling raw artifacts into interlinked wiki articles (NEW — the core value)
Linting the compiled wiki for contradictions, orphans, and gaps (NEW)
Defragging stale and duplicate artifacts (existing)

No vector DB. At personal scale (~100-400 articles), the compiled wiki fits in context windows. The wiki IS the retrieval layer.

Output:

.agents/compiled/

— encyclopedia-style markdown with

[[backlinks]]

index.md

catalog, and

log.md

chronological record.

Pluggable Compute Backend

Set

AGENTOPS_COMPILE_RUNTIME

to choose the LLM backend:

Value	Backend	Notes
`claude-cli`	Local `claude` binary	Zero-config. Inherits your Claude Code auth — no API key needed. Auto-selected if `claude` is on PATH and nothing else is set.
`ollama`	Ollama API	Default model: `gemma3:27b` . Set `OLLAMA_HOST` for remote (e.g., `bushido tunnel ollama` ).
`claude`	Claude API (HTTP)	Uses `ANTHROPIC_API_KEY` . Model: `claude-sonnet-4-20250514` .
`openai`	OpenAI-compatible	Uses `OPENAI_API_KEY` + `OPENAI_BASE_URL` .
(unset)	Claude Code session	Compilation happens inline via the current session's LLM.

When

AGENTOPS_COMPILE_RUNTIME

is unset,

ao compile

first tries to auto-detect a local

claude

binary (claude-cli runtime). If that is also absent, headless compile fails fast with an explicit error naming the env var to set. Interactive

/compile

invocations still run compilation prompts inline — the agent reading this SKILL.md IS the compiler.

Runtime preference (override auto-detect)

To force a non-auto-detected runtime permanently (e.g. you have

claude

installed but prefer Ollama for privacy), set it in

~/.agentops/config.yaml

compile:
  preferred_runtime: ollama

Precedence (high → low):

--runtime

flag,

AGENTOPS_COMPILE_RUNTIME

env,

compile.preferred_runtime

config,

claude

-binary auto-detect, empty (error).

Large-corpus batching

ao compile

passes

--batch-size

to the headless compiler (default

changed files per LLM prompt). A fresh run against a 2000+ file corpus will split into batches automatically instead of sending one giant prompt.

Flags:

```
--batch-size N
```
— files per batch (default 25)
```
--max-batches N
```
— cap batches per invocation; remaining files are picked up on the next run (default 0 = unlimited)

Execution Steps

Phase-by-phase detail lives in references/phases.md. Summary of modes:

```
/compile
```
— Full cycle: Mine → Grow → Compile → Lint → Defrag
```
/compile --compile-only
```
— Skip mine/grow, just compile + lint
```
/compile --lint-only
```
— Only lint the existing compiled wiki
```
/compile --defrag-only
```
— Only run defrag/cleanup
```
/compile --mine-only
```
— Only run mine + grow (legacy behavior)

The steps are:

Mine — extract signal from git +
```
.agents/research/
```
+ complexity hotspots
Grow — LLM-driven validation, synthesis, gap detection; adjust learning confidence
Compile — inventory → topic extraction → wiki articles with
```
[[backlinks]]
```
Lint — contradictions, orphans, missing cross-refs, stale claims
Defrag — prune stale, dedup near-duplicates, sweep oscillating goals, normalization scan
Report — write
```
.agents/compile/YYYY-MM-DD-report.md
```

See references/phases.md for the full per-phase procedure, confidence-scoring table, auto-promotion rules, template shapes for article / index / log / lint-report / compile-report, and the normalization defect scan.

Scheduling / Auto-Trigger

Lightweight defrag (prune + dedup, no mining or compilation) runs automatically at session end via the

compile-session-defrag.sh

hook. This keeps the knowledge store clean without requiring manual

/compile

invocations. The hook:

Fires on every
```
SessionEnd
```
event after
```
session-end-maintenance.sh
```
Skips silently if the
```
ao
```
CLI is not available
Runs only
```
ao defrag --prune --dedup
```
(no compilation or mining)
Has a 20-second timeout to avoid blocking session teardown

For full compilation, invoke

/compile

manually or schedule the headless compiler script with your host OS:

# Example: external cron entry for nightly compilation on bushido
0 3 * * * cd /path/to/repo && AGENTOPS_COMPILE_RUNTIME=ollama bash skills/compile/scripts/compile.sh --force

AgentOps exposes this flow through

ao compile

. If you want unattended compilation, use your host scheduler (

launchd

cron

systemd

, CI, etc.) to invoke

ao compile --force --runtime ollama

or call the lower-level

bash skills/compile/scripts/compile.sh

directly. If you want the broader private overnight loop, use

ao overnight start

instead of inventing a parallel Dream wrapper inside

/compile

Interactive Modes

These modes describe the interactive

/compile

skill behavior:

Mode	Description
`--compile-only`	Skip mine/grow, just compile + lint
`--lint-only`	Only lint the existing compiled wiki
`--defrag-only`	Only run defrag/cleanup
`--mine-only`	Only run mine + grow (legacy behavior)
`--full`	Full cycle: mine → grow → compile → lint → defrag
`--since 26h`	Time window for the mine phase
`--incremental`	Skip unchanged source files (hash-based)
`--force`	Recompile all articles regardless of hashes

Headless Script Flags

For unattended runs,

bash skills/compile/scripts/compile.sh

supports:

Flag	Default	Description
`--sources <dir>`	`.agents`	Source root for learnings, patterns, research, retros, forge, and knowledge
`--output <dir>`	`.agents/compiled`	Target directory for compiled wiki output
`--incremental`	on	Skip unchanged source files (hash-based)
`--force`	off	Recompile all articles regardless of hashes
`--lint-only`	off	Only run the lint pass on the existing compiled wiki
`--full`	on	Accepted for parity; default behavior already runs the full headless compile path

Examples

User says:

/compile

— Full Mine → Grow → Compile → Lint → Defrag cycle.

User says:

/compile --compile-only

— Just compile raw artifacts into wiki.

User says:

/compile --lint-only

— Scan existing wiki for health issues.

User says:

/compile --since 7d

— Mines with a wider window (7 days).

Scheduled externally: Nightly compilation on bushido GPU via Ollama.

Pre-evolve warmup: Run

/compile

before

/evolve

for a fresh, validated knowledge base.

Troubleshooting

Problem	Cause	Solution
`ao mine` not found	ao CLI not in PATH	Use manual fallback in Step 1
No orphaned research	All research already referenced	Skip 2b, proceed to synthesis
Empty mine output	No recent activity	Widen `--since` window
Oscillation sweep empty	No oscillating goals	Healthy state — no action needed
Ollama connection refused	Tunnel not running or wrong host	Run `bushido tunnel ollama` or check `OLLAMA_HOST`
Compilation too slow	Large corpus on small model	Use `--incremental` or switch to larger model
Hash file missing	First compilation	Normal — full compile runs, hashes saved after

Reference Documents

references/phases.md — full per-phase procedure (mine → grow → compile → lint → defrag → report)
references/confidence-scoring.md
references/knowledge-synthesis-patterns.md
references/flywheel-diagnostics.md