Documentation
Install HAM, authenticate your project, and start tracking spend.
HAM uses GitHub login for the web app and personal API keys for ingestion. The default path is short: install the CLI, connect a repo, authenticate it, and send your first data point.
1. Install the CLI
Start from the dashboard or docs and install HAM with npm or Homebrew.
2. Connect a repo
Sign in with GitHub, pick a repo, and let HAM create a project for it.
3. Authenticate once
Generate an API key, set `HAM_API_KEY`, and run `ham auth` for the repo.
Quick Start
Install and authenticate
These are the commands to get HAM working against a repo you already connected in the dashboard.
npm install -g ham-dev
brew tap kromahlusenii-ops/ham brew install ham-dev
export HAM_API_KEY=ham_your_api_key export HAM_PROJECT_ID=your_project_id
ham auth --project your_project_id
ham discover
ham benchmark --push
`ham auth` reads `HAM_API_KEY` and `HAM_PROJECT_ID`, stores repo auth locally, and configures supported editors. If both values are already exported, you do not need to pass the key on the command line.
Authentication
How auth works
HAM has two auth layers. The web app uses GitHub login. Ingestion and CLI automation use a personal API key plus a repo project id.
Web access
Sign in with GitHub to create projects, generate keys, and view analytics.
Programmatic access
Use your API key in `Authorization: Bearer ...` and pair it with `HAM_PROJECT_ID` for CLI pushes and ingest API requests.
Local Discovery
Import existing agent sessions
HAM can scan your machine for existing AI agent session logs and import them as traces. No manual data entry needed — just run ham discover and your historical spend appears in the dashboard.
ham discover --dry_run
ham discover
Supported agents
Claude Code, Codex, Gemini CLI, Cursor (partial), and Cline. Copilot and Amp are planned.
Filtering
Use --agent claude-code to limit to one agent, or --since 7d to import only recent sessions. Re-running is safe — duplicate traces are skipped.
Ingest API
Post trace data directly
If you are importing native agent logs or sending your own telemetry, post JSON to HAM with the same API key and project id.
curl -X POST https://goham.dev/api/ingest/batch \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ham_your_api_key" \
-d '{
"repo_locator": {
"repo_id": "your_repo_id",
"repo_name": "your-repo",
"git_root": "/path/to/repo",
"branch": "main"
},
"traces": [
{
"agent_family": "codex",
"agent_session_id": "session-001",
"trace_started_at": "2026-03-24T14:00:00Z",
"trace_ended_at": "2026-03-24T14:00:05Z",
"prompt_text": "Refactor the auth middleware.",
"prompt_summary": "Refactor auth middleware",
"model": "gpt-5.4",
"cwd": "/path/to/repo",
"message_index": 12,
"source_format": "codex_jsonl",
"usage": {
"input_tokens": 4820,
"output_tokens": 910,
"estimated_cost_usd": 0.14
}
}
]
}'Endpoints
Use `/api/ingest/batch` for grouped uploads or `/api/ingest/session` for single-session imports.
What to send
Include repo locator fields, timestamps, model, prompt summary, and usage totals. HAM uses the key to resolve the project.
Advanced
Token optimization and MCP
Analytics does not require scaffold or MCP first. Use the Token Optimization tab when you want to scaffold the repo and then add MCP config.
Analytics first
API-key onboarding gives you token, spend, and workflow visibility without scaffold or PR setup first.
Token optimization next
Scaffold the repo first, then add MCP when you want runtime context control and measured context savings.
One API key
The same API key can authenticate CLI flows and ingest API requests across repos you can access.
Troubleshooting
Common issues
CLI says no key found
Export `HAM_API_KEY` before running `ham auth` or pass `--key` explicitly.
CLI says no project id found
Export `HAM_PROJECT_ID` or pass `--project` to `ham auth`.
Analytics still empty
Run ham discover to import existing agent sessions, or ham benchmark --push to verify the project is authenticated.