title: Agent Workspace
shell: standard
components:
- type: header
title: Agent Workspace
eyebrow: Make your agent faster
subtitle: Codebase indexing, task tracking, and a visual board - one command to set up.
- type: section
eyebrow: The problem
heading: Your agent wastes tokens navigating
components:
- type: columns
equal_heights: true
columns:
- - type: callout
variant: warn
title: Without workspace
body: |
The agent runs `find`, `ls`, and `grep` to map the repo - burning
hundreds of tokens per turn. Context compaction wipes all that
work. The next session starts from zero. Task progress is
invisible: no handoff, no history, no way to know what's done.
- - type: callout
variant: success
title: With workspace
body: |
A two-tier anatomy index answers "what's where" in one read.
Structured task tracking survives sessions, compaction, and agent
handoffs. A visual board shows status at a glance. Git hooks fire
silently - no workflow changes.
- type: section
eyebrow: Setup
heading: One command
components:
- type: code
language: bash
code: |
kazam workspace init
- type: markdown
body: |
That single command does four things:
1. Scans the codebase and writes `.kazam/ctx/anatomy.tsv` (root files)
and `.kazam/ctx/anatomy/<dir>.tsv` (per-directory detail files).
2. Installs git hooks - session-start, post-write, session-stop.
3. Writes `.claude/rules/kazam-workspace.md` (or equivalent) so your
agent knows the conventions automatically.
4. Creates `.kazam/track/tasks.yaml` ready for task entries.
- type: markdown
body: |
Once initialized, open the visual board in a separate terminal while
your agent works:
- type: code
language: bash
code: |
kazam board
- type: section
eyebrow: Navigation
heading: Two-tier codebase index
components:
- type: markdown
body: |
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.
- type: code
language: text
code: |
# .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
- type: markdown
body: |
After reading an unfamiliar file, enrich its description so future
reads skip it:
- type: code
language: bash
code: |
kazam ctx describe src/render/components.rs "renders every component type to HTML"
- type: section
eyebrow: Tracking
heading: Structured and persistent
components:
- type: markdown
body: |
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.
- type: code
language: bash
code: |
# 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
- type: markdown
body: |
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.
- type: section
eyebrow: Visibility
heading: Visual workspace
components:
- type: markdown
body: |
`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.
- type: code
language: bash
code: |
kazam board # opens at localhost:3001, watches .kazam/ for changes
- type: section
eyebrow: Handoff
heading: Putting a file in front of you
components:
- type: markdown
body: |
An agent can open a browser tab. It cannot find the right window in your
editor and scroll to the right file. `kazam open` and `kazam show` close
that gap.
Both take exactly one file, and only `.md`, `.yaml`, `.yml`, or `.json`.
Any other extension is rejected by name, so a typo fails loudly instead
of rendering garbage.
- type: code
language: bash
code: |
kazam open notes.md # browser, live reload, editable
kazam show config.yaml # terminal, syntax colored
- type: markdown
body: |
`kazam open` renders markdown as HTML and shows YAML or JSON with line
numbers and per-token coloring. The toolbar has View, Edit, and Copy.
Selecting text copies it, in the rendered view and in the editor both.
The reason it is a server and not a preview window is the API sitting
next to the page. You type notes in the browser and the agent reads them
without you saving anything:
- type: table
columns:
- key: route
label: Route
- key: does
label: Returns
rows:
- route: GET /api/content
does: Raw text. Unsaved browser edits take priority over what is on disk
- route: POST /api/content
does: Replaces the in-memory buffer. Reports whether the text still parses
- route: POST /api/save
does: Writes the buffer to disk. Refused while a conflict is unresolved
- route: GET /api/rendered
does: Rendered HTML for the current text
- route: GET /api/status
does: dirty, conflict, valid, and the parse error when there is one
- type: callout
variant: info
title: Unsaved edits survive a disk write
body: |
If the file changes on disk while your buffer is dirty, the page does not
reload over your work. It shows a conflict bar with Keep mine and Load
from disk, and leaves the choice to you. Agents should check
`GET /api/status` before writing a file someone has open.
- type: callout
variant: info
title: Saving is explicit
body: |
Edits sit in memory until you hit Save or press Cmd+S. Nothing autosaves,
because writing on every keystroke would churn the file and fire your agent
hooks over and over. Agents can save too, with `POST /api/save`.
The write goes to a temp file and then gets renamed, so a crash cannot leave
a half-written file. A save is refused while the conflict bar is up, since
the file moved underneath your buffer and saving would overwrite whatever
landed there.
- type: section
eyebrow: Wiring
heading: Invisible hooks
components:
- type: markdown
body: |
Three hooks install automatically. They fire silently - no prompts,
no workflow changes required.
- type: columns
equal_heights: true
columns:
- - type: callout
variant: info
title: session-start
body: 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.
- - type: callout
variant: info
title: post-write
body: 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.
- - type: callout
variant: info
title: session-stop
body: 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.
- type: section
eyebrow: Results
heading: Real-world benchmarks
components:
- type: table
columns:
- key: repo
label: Repo
sortable: true
- key: files
label: Files
sortable: true
align: right
- key: task
label: Task
- key: cost
label: Cost
sortable: true
- key: speed
label: Speed
sortable: true
rows:
- repo: Internal tools repo
files: "8,000+"
task: Add CLI flag + thread to SQL
cost: 45% cheaper
speed: 41% faster
- repo: Plugin repo
files: "126"
task: Add config field to skill
cost: 44% cheaper
speed: 59% faster
- repo: React/TS app
files: "89"
task: Add loading skeleton
cost: 46% cheaper
speed: 47% faster
- repo: Python service
files: "233"
task: Cross-cutting model change
cost: 45% cheaper
speed: 44% faster
- type: markdown
body: |
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.
- type: section
eyebrow: Learning
heading: Correction ledger
components:
- type: markdown
body: |
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.
- type: code
language: bash
code: |
# 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
- type: markdown
body: |
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.
- type: section
eyebrow: Maintenance
heading: Consolidation
components:
- type: markdown
body: |
Over time, resolved bugs pile up and learnings duplicate. `consolidate`
cleans house - removes resolved bugs older than N days and deduplicates
learnings.
- type: code
language: bash
code: |
# Default: remove resolved bugs older than 30 days
kazam ctx consolidate
# Custom window
kazam ctx consolidate --days 14
- type: markdown
body: |
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.
- type: section
eyebrow: Customization
heading: Rules override
components:
- type: markdown
body: |
`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.
- type: code
language: bash
code: |
# 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
- type: markdown
body: |
The override file is plain markdown. It's version-controlled with the
rest of `.kazam/`, so team-wide conventions propagate through git.
- type: callout
variant: info
title: Next up
body: "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."
links:
- label: Quickstart guide →
href: guide.html
variant: primary
- label: Components reference
href: components/index.html
variant: secondary