Decant#
Decant shows where your coding agents spend tokens, money, and time. It reads
the session logs that Claude Code, Codex, Gemini CLI, OpenCode, Cursor CLI,
GitHub Copilot CLI, Copilot Chat in VS Code, Hermes Agent, and Pi already write
on your machine, plus ATIF
trajectories you import, into one searchable archive. You explore it in a local web UI or from
the command line.
Built by
Dosu.
https://github.com/user-attachments/assets/188f7cca-5b0a-4504-8eb2-a317a606d91e
Quick start#
npx @dosu/decant@latest
You don't need Bun or a global install. The command indexes the agent logs it
finds, starts the web UI at http://127.0.0.1:3000, and keeps watching for new
sessions. For a persistent decant command, see Installation.
Features#
- One SQLite archive for every supported agent, with full-text search across
prompts, responses, tool names, and tool inputs. - Session transcripts, with diagnostics for records Decant could not parse
or skipped under its input limits. - Token, estimated cost, context-window, and agent-time
analytics by agent, model, project, repository (including worktrees), outcome,
and day. - File hotspots, tool usage, and MCP server usage across sessions.
- Recommendations drawn from patterns in your sessions, each with a suggested
change you can mark as implemented. - Session exports to Markdown, JSON, Letta's trajectory-v1, and ATIF.
- HTML reports of the analytics view or a single session. Reports leave out
transcript messages and tool bodies but include project paths, and a session
report adds its title, a prompt preview, and file paths. Review a report
before you share it. - Workflow scripts, session replays, and agent instructions (
SKILL.md,
AGENTS.mdsections, and slash commands) distilled from command history. - A local HTTP API with an OpenAPI 3.1 contract.
Supported agents#
Decant finds each agent's logs in its default location. To point it somewhere
else, or for per-agent details, see Sources.
| Agent | Default location | Token usage |
|---|---|---|
| Claude Code | ~/.claude/projects | Recorded |
| Codex | ~/.codex | Recorded |
| Gemini CLI | ~/.gemini/tmp | Recorded |
| OpenCode 1.2 and later | ~/.local/share/opencode | Recorded |
| Cursor CLI | ~/.cursor/chats | Not recorded by Cursor |
| GitHub Copilot CLI | ~/.copilot/session-state | Recorded, priced at the model's API rates |
| Copilot Chat in VS Code | VS Code's User directory | VS Code builds from April 2026 on, as a rough estimate |
| Hermes Agent | ~/.hermes | Recorded per session and model, not per message |
| Pi | ~/.pi/agent/sessions | Recorded |
| ATIF trajectories | ~/.decant/atif | From step metrics or final_metrics |
When an agent records no usage, Decant shows tokens and cost as unavailable
instead of $0.
Where does my data go?#
Decant is local-first. It makes no outbound network calls at runtime, and your
transcripts never leave your machine. The one exception is an update check that
stays off until you turn it on. See Updating.
Important
Decant does keep a copy of your transcripts. To make sessions searchable, it
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, including
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, the archive is subject to it. See
What the archive stores to
inspect, delete, or remove it.
Installation#
Note
Published binaries support macOS and Linux on x64 and arm64. Native Windows
binaries are not currently available.
npm#
npm install --global @dosu/decant@latest
decant
The npm package is a small launcher that runs the matching native binary. It
needs Node.js 18 or newer, and does not need Bun.
Homebrew#
brew install dosu-ai/dosu/decant
decant
Shell installer#
This installs the latest release without Node.js or Bun:
curl -fsSL https://raw.githubusercontent.com/dosu-ai/decant/main/install.sh | sh
decant
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" \
-v "$HOME/.cursor/chats:/sources/cursor:ro" \
-v "$HOME/.copilot/session-state:/sources/copilot:ro" \
-v "$HOME/Library/Application Support/Code/User:/sources/vscode:ro" \
-v "$HOME/.decant/atif:/sources/atif:ro" \
ghcr.io/dosu-ai/decant:latest
The VS Code mount shows the macOS path. On Linux, mount
$HOME/.config/Code/User instead.
Warning
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. Run docker volume rm decant-data when you want it gone.
From source#
Source builds need Bun 1.3 or newer. Follow the steps under
Contributing.
Distribution covers installer options, native builds,
and release verification.
Updating#
decant update # install the newest release in place
decant update --check # only report whether one exists
decant update uses the tool that installed Decant. It runs
npm install --global for npm and brew update and brew upgrade for
Homebrew, and makes a checksum-verified download for the shell installer.
Docker, npx, source checkouts, and binaries Decant did not install print how
to update instead.
To hear about new releases, turn on Check for updates in Settings or set
DECANT_UPDATE_CHECK=1. Decant then asks the npm registry for the newest
version once a day and shows a notice in the sidebar and after CLI commands.
The request carries no session data.
Usage#
Web UI#
Run decant with no arguments to sync your sessions, start the UI at
http://127.0.0.1:3000, and open it in your browser. decant serve --no-open
skips the browser, and --host and --port change the address.
To keep Decant running without a terminal, turn on Run in the background in
Settings or run decant service install. It then starts at login on macOS and
Linux. See Running in the background.
| Page | What it shows |
|---|---|
| Analytics | Token, cost, context, and agent-time rollups across sessions |
| Insights | Recommendations drawn from your history, the ones you have implemented, and general setup ideas not derived from your archive |
| Sessions | Sessions and their retained transcript messages |
| Search | Full-text matches in prompts, responses, tool names, and tool inputs |
| Projects | Sessions and cost for each project |
| Files | The files agents read, edit, and write most |
| Tools & MCP | Tool calls and MCP server usage |
CLI#
decant # start the local web UI
decant sync # index new and changed sessions
decant ls # list sessions
decant ls --repo . --since 2026-11-01 # this repository and its worktrees
decant ls --json --fields id,title # only the fields you name
decant show 1 # render a transcript
decant show 1 --outline # list its messages and their sizes
decant search "auth bug" # full-text search
decant project ls --limit 20 # projects with session counts and cost
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 export 1 --as atif # also md, json, and trajectory
decant export --mirror ~/atif # keep a folder of ATIF documents, one per session
decant distill script # workflow script from command history
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
decant db compact # losslessly compress stored source records
decant update # update Decant with the tool that installed it
decant service install # start Decant at login and keep it running
decant doctor # redacted environment report for bug reports
Run decant --help or decant <command> --help for every command and flag.
Read commands support --json. Global flags include --db, --format,
--quiet, --no-color, and --no-sync. --db or DECANT_DB sets the
archive path. A read command does not create an archive at a path you name, so
a mistyped path is an error.
Commands exit 0 on success, 1 when the command fails, 2 on a usage error, and 3
when sync drops lines it cannot parse. With --json, an error is a JSON
object with a stable code on stderr. See
CLI output, errors, and exit codes.
Read one session in pieces#
decant show <id> prints the whole transcript, which can be megabytes for a
long session. To read part of one, list its messages first and then ask for
the ones you need:
decant show 1 --outline # one row per message
decant show 1 --offset 10 --limit 5 # five messages, starting at index 10
decant show 1 --limit 20 --max-chars 2000 # cut long text and tool output
| Flag | What it does |
|---|---|
--outline | Prints one row per message with its index, role, size in characters, block kinds, and tool names. Message bodies are left out, except that each user prompt row ends with the first 80 characters of the prompt. With --json, the outline array holds up to 240 characters of each prompt. Read the whole message with --offset <index> --limit 1. |
--limit <n> | Shows at most n messages. |
--offset <n> | Skips the first n messages. The outline's index column is the offset of each message. |
--max-chars <n> | Cuts each text, tool input, and tool output to n characters. |
--limit and --offset read the same page that message_limit and
message_offset return from GET /api/sessions/{id}, and they also page the
outline. Without any of these flags, show prints what it always has.
Text output ends with the range it covers, such as
[showing 5 of 64 messages from offset 10], and with the command for the next
page when there is one. Each cut is marked where the content stops:
[truncated: 3000 of 5000 chars omitted. Raise --max-chars to read more.].
With --json, the result adds message_count, message_offset,
message_limit, has_more_messages, and partial. partial is true when
messages were skipped, messages remain, or a block was cut. --max-chars also
adds max_chars and truncated_blocks, and each cut block carries
truncated: true and original_chars, the length of each cut field before the
cut. --outline --json holds the per-message rows in messages and the items
of GET /api/sessions/{id}/outline in outline.
show and export take Decant's session id or the id the source tool gave the
session, such as the Claude Code session UUID in its transcript file name. An
integer names the Decant id first. When one source id belongs to sessions from
two tools, the command exits 2 and lists each match with its id, tool, and
start time.
decant ls and decant search take the same scope flags:
--project <path>matches one project directory. Decant resolves., a
relative path,~, a trailing slash, and a symlink before it compares.--repo <value>matches a repository, its worktrees, and any other checkout
with the sameoriginremote. The value is a directory inside the repository
(--repo .works from a worktree or a subdirectory), a remote such as
github.com/acme/widget, or the name of the repository's directory. A bare
name such aswidgetis checked against repository names first, so write
./widgetto mean a folder in the current directory.--sinceand--untiltakeYYYY-MM-DDdays in UTC. Both days are
included, and each session counts on the UTC day it started, including a
session whose log records a local time with an offset.--limitand--offsetpage through the rows.
A path or repository the archive has never recorded exits with code 1 and an
error on stderr, so an empty list always means the scope is known and holds no
matching session.
decant ls --json prints every field of each session. --fields keeps only
the fields you name, in the order you name them, on both decant ls and
decant project ls. Without --json they print as tab-separated columns. An
unknown field is a usage error that lists the valid names. decant project ls
prints every project unless --limit and --offset say otherwise.
Local API#
decant serve also serves a local HTTP API. Its 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#
Using Decant:
- CLI output, errors, and exit codes
- Sources and where Decant finds them
- How the analytics are calculated
- Pricing estimates and their sources
- What the archive stores, and how sync and deletion work
- Install channels, updates, and release verification
- Local API routes and recipes
- Operational logging
Working on Decant:
Contributing#
Contributions are welcome. Bug fixes, pricing updates, and documentation fixes
can go straight to a pull request. New sources, commands, UI features, and
changes to existing behavior need an issue or a
discussion first, where a
maintainer agrees on the direction and scope.
To run Decant from source, install Bun 1.3 or newer, then:
git clone https://github.com/dosu-ai/decant.git
cd decant
bun run dev
bun run dev installs dependencies, starts the UI at http://127.0.0.1:3000,
indexes your sessions, and watches for changes. Before you open a pull request,
run:
bun test
bunx tsc --noEmit
bunx biome check .
Read CONTRIBUTING.md for the full checklist, including
commit signing and the pull request template. 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.
Community and support#
- Ask questions and share ideas in
GitHub Discussions. - Report bugs with the
issue templates, and
paste the output ofdecant doctor. It reports versions, platform, and
per-source counts without any transcript content. - Report security vulnerabilities privately as described in
SECURITY.md. - Everyone who takes part follows the Code of Conduct.
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.