169 lines
6.2 KiB
Markdown
169 lines
6.2 KiB
Markdown
# 𝄋 anth
|
|
|
|
**Independent tools for working with Anthropic product data.**
|
|
|
|
anth is a Rust toolkit for reading and analyzing data produced by Anthropic's AI products. It ships two command-line tools and a library for building your own.
|
|
|
|
> [!CAUTION]
|
|
> **Alpha software.** anth is under active development and not fully battle-tested. APIs may change between releases. Use at your own risk.
|
|
>
|
|
> **Not affiliated with Anthropic.** This is an independent, unofficial project. *Claude* and *Claude Code* are trademarks of Anthropic, PBC. anth is not endorsed by, sponsored by, or affiliated with Anthropic in any way.
|
|
|
|
---
|
|
|
|
## Tools
|
|
|
|
### `anth_usage` — token usage capture `beta`
|
|
|
|
Launches Claude Code in a pseudo-terminal, sends the `/usage` command, and captures the output as structured data. Useful for tracking costs, monitoring consumption, or feeding usage metrics into dashboards.
|
|
|
|
**Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and available as `claude` on your PATH.**
|
|
|
|
```bash
|
|
# Default: JSON output of token usage
|
|
anth_usage
|
|
|
|
# Raw terminal output (for debugging)
|
|
anth_usage --raw
|
|
|
|
# Specify a working directory
|
|
anth_usage --workdir /path/to/project
|
|
|
|
# Use current directory
|
|
anth_usage --cwd
|
|
```
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--debug` | Enable debug logging to stderr |
|
|
| `--raw` | Output raw screen content instead of parsed JSON |
|
|
| `--no-trust` | Fail if Claude Code prompts for folder trust (instead of auto-confirming) |
|
|
| `--workdir <path>` | Working directory for Claude Code |
|
|
| `--cwd` | Use current working directory |
|
|
|
|
How it works: anth_usage spawns a PTY, waits for Claude Code's UI to render, handles the folder trust prompt if needed, sends `/usage`, and parses the terminal output via a vt100 emulator. The result is structured JSON with token counts and cost data.
|
|
|
|
Install:
|
|
|
|
```bash
|
|
cargo install --git https://git.g4b.org/dirigence/dirigent_anth --bin anth_usage
|
|
```
|
|
|
|
---
|
|
|
|
### `anth_bear` — session inspector `beta`
|
|
|
|
Browse and search Claude Code's local session storage (`~/.claude/projects/`). Validates parsing, searches message content, and reports aggregate statistics.
|
|
|
|
```bash
|
|
# Validate all sessions parse correctly
|
|
anth_bear validate
|
|
|
|
# Search user and assistant messages
|
|
anth_bear search "database migration"
|
|
|
|
# Aggregate statistics — tool usage, message counts
|
|
anth_bear stats
|
|
```
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `validate` | Parse all sessions, report errors, count messages/tools/subagents |
|
|
| `search <query>` | Case-insensitive search across user and assistant messages |
|
|
| `stats` | Aggregate statistics: project counts, tool usage rankings (top 15) |
|
|
|
|
Install:
|
|
|
|
```bash
|
|
cargo install --git https://git.g4b.org/dirigence/dirigent_anth --bin anth_bear
|
|
```
|
|
|
|
---
|
|
|
|
## Library `production`
|
|
|
|
The tools above are built on the anth library. Use it to build your own session browsers, usage analyzers, and archival tooling.
|
|
|
|
Claude Code stores every session as JSONL on the local filesystem. Each line is a message — user input, assistant response, tool call, tool result, meta event. The format is lenient (fields come and go between releases) and noisy (streamed assistant messages produce many partial lines that should collapse to one).
|
|
|
|
anth reads those files and gives you back well-typed structs:
|
|
|
|
- **Discovery** — scan `~/.claude/projects/` for projects and sessions
|
|
- **Lenient parsing** — line-by-line `BufReader`, unknown fields ignored, format drift tolerated
|
|
- **Streaming dedup** — collapse streamed assistant messages by `uuid` to their final version
|
|
- **Tool correlation** — pair `tool_use` ↔ `tool_result` by `tool_use_id`, including parallel calls
|
|
- **Conversation tree** — reconstruct `uuid` / `parentUuid` threading, with branch detection
|
|
- **Noise classification** — flag meta messages, warmup, interruptions, API errors
|
|
- **Sub-agent loading** — recursive parsing of sub-agent JSONL with metadata
|
|
- **Cross-platform paths** — `camino::Utf8PathBuf` throughout for Windows + Unix
|
|
|
|
### Quick start
|
|
|
|
```rust
|
|
use dirigent_anth::{discover_claude_home, discover_projects, load_session};
|
|
|
|
let home = discover_claude_home()?;
|
|
let projects = discover_projects(&home)?;
|
|
|
|
for project in &projects {
|
|
for session in &project.sessions {
|
|
let parsed = load_session(&session.path)?;
|
|
println!("{}: {} messages, {} tool calls",
|
|
session.id,
|
|
parsed.messages.len(),
|
|
parsed.tool_calls.len());
|
|
}
|
|
}
|
|
```
|
|
|
|
### Library dependency
|
|
|
|
```toml
|
|
[dependencies]
|
|
dirigent_anth = { git = "https://git.g4b.org/dirigence/dirigent_anth" }
|
|
```
|
|
|
|
### Modules
|
|
|
|
| Module | Purpose |
|
|
|--------|---------|
|
|
| `types` | Public data types — `Content`, `ContentBlock`, `RawMessage` variants, `ToolCall` |
|
|
| `parser` | JSONL line and file parser with lenient error handling |
|
|
| `dedup` | Streaming deduplication of assistant messages by uuid |
|
|
| `correlation` | Tool call ↔ result pairing by `tool_use_id` |
|
|
| `tree` | Conversation tree from uuid / parentUuid relationships |
|
|
| `noise` | Meta / warmup / interruption / API-error classification |
|
|
| `discovery` | Filesystem scanning for Claude projects and sessions |
|
|
| `subagent` | Sub-agent JSONL and metadata loading |
|
|
| `util` | Timestamp parsing — ISO 8601, Unix seconds, Unix milliseconds |
|
|
|
|
---
|
|
|
|
## Design principles
|
|
|
|
1. **Types are the product.** Downstream consumers depend on the structs, not the binaries.
|
|
2. **Lenient parsing.** Unknown fields are ignored; unknown message types are logged and skipped. Claude Code format changes between releases — anth keeps reading.
|
|
3. **Stream-oriented.** Line-by-line `BufReader`. Sessions can be large; nothing is loaded whole.
|
|
4. **Sync-first.** File parsing is CPU-bound. No async overhead.
|
|
5. **Cross-platform.** `camino::Utf8PathBuf` for Windows / Unix parity.
|
|
|
|
---
|
|
|
|
## About this repository
|
|
|
|
This is a downstream mirror. anth is developed inside the upstream
|
|
[Dirigent](https://git.g4b.org/dirigence/dirigent) monorepo and exported here
|
|
for standalone distribution. Issues and pull requests are accepted on the
|
|
`develop` branch, but canonical development happens upstream.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Licensed under either of
|
|
|
|
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
|
|
- MIT License ([LICENSE-MIT](LICENSE-MIT))
|
|
|
|
at your option.
|