Decant#

Decant turns the Claude Code, Codex, and Gemini CLI session logs on your machine
into tangible insights. See where tokens, cost, and agent time go, inspect
context usage, find the files and tools agents touch, and search complete
transcripts from a CLI or local web UI.

Decant is local-first. It makes no outbound network calls at runtime, and your
transcripts never leave your machine.

It does keep a copy of them. To make sessions searchable, Decant writes prompts,
tool inputs, tool output, and canonicalized raw records for retained transcript
messages into an unencrypted SQLite archive at ~/.decant/decant.db, with a
full-text index over the prompt and tool-argument text. Whatever your agents read
is in there too — source code, file contents, local paths, and any credentials
pasted into a session. Decant creates the archive owner-only (0600). If your
organization has a retention policy for agent transcripts, this archive is
subject to it. See
What the archive stores to
inspect, delete, or remove it.

Built by
Dosu,
Knowledge Infrastructure for Agents. Dosu helps make agents faster, cheaper,
and more effective.

Quick start#

Run Decant with npx with no Bun install or global package required.

npx @dosu/decant@latest

This starts the local UI at http://127.0.0.1:3000, indexes the Claude Code,
Codex, and Gemini CLI logs on your machine, and watches for changes.

What you get#

• One SQLite archive for Claude Code, Codex, and Gemini CLI sessions.
• Full-text search across messages, tool calls, and transcripts.
• Token, estimated cost, context, activity, tool, MCP, and
  file analytics.
• Browsable sessions, projects, files, and ingest diagnostics.
• Markdown, JSON, report, and trajectory exports.
• Deterministic scripts, replays, and agent instructions distilled from command
  history.

Install#

Published binaries support macOS and Linux on x64 and arm64. Native Windows
binaries are not currently available.

Install a persistent command with npm:

npm install --global @dosu/decant@latest
decant

Or use Homebrew:

brew install dosu-ai/dosu/decant
decant

Or install the latest release without Node.js or Bun:

curl -fsSL https://raw.githubusercontent.com/dosu-ai/decant/main/install.sh | sh
decant

See Distribution for installer options, Docker, source
builds, and release verification.

Docker#

docker run --rm \
  -p 127.0.0.1:3000:3000 \
  -v decant-data:/var/lib/decant \
  -v "$HOME/.claude/projects:/sources/claude:ro" \
  -v "$HOME/.codex:/sources/codex:ro" \
  -v "$HOME/.gemini/tmp:/sources/gemini:ro" \
  ghcr.io/dosu-ai/decant:latest

Keep the 127.0.0.1: prefix. Publishing -p 3000:3000 exposes the
unauthenticated archive API on every host interface. Custom container networks
may need the trusted-peer setting documented under
Docker distribution.

The source mounts are read-only, but decant-data is a named volume: the
archive outlives every container, and neither --rm nor docker rm removes it.
Use docker volume rm decant-data when you want it gone.

CLI#

decant # start the local web UI
decant sync # index new and changed sessions
decant ls # list sessions
decant show 1 # render a transcript
decant search "auth bug" # full-text search
decant stats --by model # usage and cost rollups
decant economics # token, cost, and time breakdowns
decant files --group ext # file hotspots
decant tool stats # tool usage
decant mcp stats # MCP server usage
decant export 1 > session.md # export a session
decant db info # what the archive holds and where
decant session rm 1 --yes # delete a session and its descendants
decant db vacuum # release the freed pages after a delete

Run decant --help or decant <command> --help for all commands and flags.
Read commands support --json; global flags include --db, --format,
--quiet, --no-color, and --no-sync.

Decant reads ~/.claude/projects, ~/.codex, and ~/.gemini/tmp by default.
Override them with DECANT_CLAUDE_DIR, DECANT_CODEX_DIR, and
DECANT_GEMINI_DIR, or with the corresponding --claude-dir, --codex-dir,
and --gemini-dir flags on sync, watch, and serve.

To index selected files or a temporary source tree:

decant --db /tmp/decant.db sync --path ./session.jsonl --path ./sessions

Local API#

The OpenAPI 3.1 contract is docs/api/openapi.yaml, and
a running server exposes it at
http://127.0.0.1:3000/api/openapi.json. See API recipes
for examples.

Documentation#

• Analytics methodology
• Pricing estimates
• Archive and data lifecycle
• Local Serve API
• Distribution and release verification
• Architecture

Contributing#

Contributions are welcome. Read CONTRIBUTING.md for setup,
tests, and privacy requirements. Coding agents should also read
AGENTS.md.

Use synthetic session data in issues and tests. Real transcripts can contain
source code, prompts, credentials, and local paths.

Security#

Report vulnerabilities privately as described in SECURITY.md.

About Dosu#

Decant is built and maintained by
Dosu,
Knowledge Infrastructure for Agents. Dosu helps make agents faster, cheaper,
and more effective. Decant shows what your agents spent, read, and touched via
your agent logs.

Acknowledgments#

Decant was inspired in part by
Letta's Trajectory, which normalizes
agent transcripts across runtimes into a shared record format.

License#

Decant is licensed under the Apache License 2.0.