Agent Workspace
Codebase indexing, task tracking, and a visual board — one command to set up.
One command
kazam workspace init
That single command does four things:
- Scans the codebase and writes
.kazam/ctx/anatomy.tsv(root files) and.kazam/ctx/anatomy/<dir>.tsv(per-directory detail files). - Installs git hooks — session-start, post-write, session-stop.
- Writes
.claude/rules/kazam-workspace.md(or equivalent) so your agent knows the conventions automatically. - Creates
.kazam/track/tasks.yamlready for task entries.
Once initialized, open the visual board in a separate terminal while your agent works:
kazam board
Two-tier codebase index
Navigation is a two-step read, not a filesystem crawl.
Step 1 — summary..kazam/ctx/anatomy.tsv lists every root file with token counts and descriptions, plus a rollup for each directory (file count, total tokens, one-line description). Even for repos with thousands of files this summary is ~68 lines — one read, full orientation.
Step 2 — detail..kazam/ctx/anatomy/<dir>.tsv lists every file in that directory with per-file metadata. Nested paths use -- as separator: frontend/src/app → anatomy/frontend--src--app.tsv.
Go summary → detail file → source file. No ls, no find, no grep for structure.
# .kazam/ctx/anatomy.tsv (excerpt)
# scanned: 2026-04-30T15:07:11Z
# root_files
path tokens reads description
README.md 1367 0 Project overview and install instructions
Cargo.toml 209 0 Rust package manifest
# directories
path files tokens description
src 33 123608 Core rendering and build pipeline
docs 26 44858 kazam documentation site source
After reading an unfamiliar file, enrich its description so future reads skip it:
kazam ctx describe src/render/components.rs "renders every component type to HTML"
Structured and persistent
Tasks live in .kazam/track/tasks.yaml. They survive session ends, context compaction, and agent handoffs. The workspace rules file instructs agents to close tasks immediately after each commit — no batching, no forgetting.
# See what's ready to work on (unblocked, sorted by priority)
kazam track ready --json
# Claim a task before starting
kazam track claim TASK-12 --name claude
# Close it after the commit lands
kazam track close TASK-12 --reason "added retry logic in src/client.rs"
# Mark blocked if something is in the way
kazam track block TASK-14 --reason "waiting on human approval for schema change"
# Full list with status
kazam track list --json
Tasks with --owner human are not for agents to close. If one blocks progress, mark it blocked and move on. When the human resolves it, close it for them.
Visual workspace
kazam board opens a themed, auto-refreshing dashboard in the browser. It watches .kazam/ for changes and updates without a page reload.
The board shows:
- Task list by status (open, claimed, blocked, closed)
- Anatomy index with file counts and token budgets
- Recent activity from the post-write hook log
Run it in a separate terminal while the agent works. No config needed — it picks up the site theme from kazam.yaml if one exists.
kazam board # opens at localhost:3000, watches .kazam/ for changes
Invisible hooks
Three hooks install automatically. They fire silently — no prompts, no workflow changes required.
Checks anatomy freshness and surfaces ready tasks. If the anatomy is stale (files changed since last scan), it rescans before the agent's first read.
Logs each file modification to .kazam/activity.yaml with a timestamp and path. The board and anatomy stay current without a manual rescan after every edit.
Rescans the anatomy on exit so the next session — human or agent — opens with a fresh index. No manual kazam workspace scan needed between sessions.
Real-world benchmarks
| Repo | Files | Task | Cost | Speed |
|---|---|---|---|---|
| Internal tools repo | 8,000+ | Add CLI flag + thread to SQL | 45% cheaper | 41% faster |
| Plugin repo | 126 | Add config field to skill | 44% cheaper | 59% faster |
| React/TS app | 89 | Add loading skeleton | 46% cheaper | 47% faster |
| Python service | 233 | Cross-cutting model change | 45% cheaper | 44% faster |
Tested with Sonnet 4.6, identical prompts, git worktrees. Input tokens per turn dropped 81–94% across the board — the anatomy index eliminates exploratory file reads.
Correction ledger
When an agent gets something wrong — misreads a file, applies the wrong pattern, makes a false assumption — record it so future sessions don't repeat the mistake.
# Record a correction
kazam ctx correction "assumed auth middleware was Express" "it's a custom Koa middleware" --file src/auth.rs
# List all corrections
kazam ctx corrections --json
Corrections are surfaced in the workspace rules file. Agents read them at session start and avoid repeating the same mistakes. Over time this builds a project-specific error log that makes every session smarter than the last.
Consolidation
Over time, resolved bugs pile up and learnings duplicate. consolidate cleans house — removes resolved bugs older than N days and deduplicates learnings.
# Default: remove resolved bugs older than 30 days
kazam ctx consolidate
# Custom window
kazam ctx consolidate --days 14
Run this periodically (or let a scheduled agent do it) to keep .kazam/ctx/ lean. Less stale data means fewer tokens spent on context that no longer matters.
Rules override
kazam workspace init writes a default rules file for your agent (e.g. .claude/rules/kazam-workspace.md). If the defaults don't fit, create .kazam/ctx/rules-override.md — its contents are appended to the generated rules on every workspace init or rescan.
# Create an override file
cat > .kazam/ctx/rules-override.md << 'EOF'
## Project-specific rules
- Always run `make lint` before committing.
- The `legacy/` directory is frozen — never modify files there.
- Prefer integration tests over unit tests in this repo.
EOF
# Re-init to pick up the override
kazam workspace init --agent claude
The override file is plain markdown. It's version-controlled with the rest of .kazam/, so team-wide conventions propagate through git.
Get the binary and run kazam workspace init in any repo. Then see the components reference for the static site gen side — every primitive you can drop into a kazam page.