rana

AI Engineering CLI — manage Claude Code and Codex accounts, monitor agents, and track usage.

 _ __ __ _ _ __   __ _
| '__/ _` | '_ \ / _` |
| | | (_| | | | | (_| |
|_|  \__,_|_| |_|\__,_|

Install

npm install -g rana-cli

Or for local development:

git clone <repo>
cd rana
npm install
npm run build
npm link

Quickstart

# First run — wizard appears automatically
rana switch claude

# Apply the account to your shell
eval $(rana switch claude)

# Open the web dashboard
rana dash

# Watch your agents in real time
rana agent watch

Commands

rana switch <tool>

Switch the active account for a given AI tool.

Command	Description
rana switch claude	Auto-pick the Claude Code account with most budget headroom
rana switch claude --force	Open interactive account selector UI
rana switch codex	Auto-pick the best Codex account
rana switch codex --force	Open interactive Codex account selector

The command prints eval-able export statements. Apply them with:

eval $(rana switch claude)

On first run with no accounts configured, a setup wizard launches automatically:

Welcome to rana

No accounts found. Add your first one.

Account name:  › personal
Tool:          › Claude Code
Auth path:     › ~/.claude
Monthly budget:› 50

✔ "personal" saved. Add another? › Yes / No

Interactive Selector (--force)

Select account              budget used
❯ personal   Claude Code   ███░░  31%  $15/$50   ✔ recommended
  work        Claude Code   ████░  84%  $84/$100
  client-a    Codex         █░░░░   8%  $16/$200
↑↓ move · Enter select · N add new · D delete · Esc cancel

---

rana agent

Read and monitor Claude Code agent sessions from ~/.claude/projects/.

Command	Description
rana agent list	Tree view of all active agents
rana agent tasks	Shared task board across all sessions
rana agent log <role>	Live-tail the summarized log for an agent
rana agent status <role>	Full detail card for an agent
rana agent watch	Compact live team view, refreshes every 2s

rana agent list

role           type           status       model          runtime  tokens
─────────────────────────────────────────────────────────────────────────────
lead           orchestrator   ● active     claude-sonnet  1h12m    94k tokens
└── backend    teammate       ● active     claude-sonnet  48m      31k tokens
└── frontend   teammate       ✔ done       claude-sonnet  22m      14k tokens

rana agent log <role>

[14:22:09]  WRITE    Implemented JWT validation middleware
            why:     Missing expiry check caused silent auth bypass
[14:22:19]  MESSAGE  Notified frontend — token interface ready at types/auth.ts
[14:22:31]  READ     Inspected login route before refactoring
[14:22:44]  BLOCKED  Waiting on frontend to confirm token shape

Options:

• --last <n> — print N most recent entries and exit
• --raw — skip summarization, show raw tool call data

---

rana dash

Start the web dashboard.

Command	Description
rana dash	Start server, open browser at localhost:4242
rana dash --port <n>	Use a custom port
rana dash --export	Dump usage to CSV and exit

The dashboard has four panels (updates via WebSocket):

1. Agent Tree — live tree with status, model, runtime, tokens. Click to focus.
2. Task Board — kanban columns: Pending / Running / Done.
3. Log Feed — summarized log stream for the selected agent.
4. Agent Detail — model, tokens in/out, cost, tasks.

Usage strip (always visible at bottom) shows per-account monthly usage with progress bars.

---

rana help

rana help             # main help screen
rana help switch      # detailed help for switch command
rana help agent       # detailed help for agent command
rana help dash        # detailed help for dash command

---

Configuration

Account storage

Accounts are stored at ~/.rana/accounts/<name>.json with chmod 600.

{
  "name": "personal",
  "tool": "claude",
  "authPath": "/home/you/.claude",
  "budgetUsd": 50,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

Runtime data

Path	Contents
~/.rana/config.json	Global rana settings
~/.rana/accounts/	One JSON per account
~/.rana/usage.db	SQLite usage history
~/.rana/scheduler-state.json	Current scheduler recommendation
~/.rana/logs/	Summary cache + CSV exports

Environment variables

Variable	Effect
ANTHROPIC_API_KEY	Enables Claude API summarization in agent log
RANA_BANNER_SHOWN	Set to 1 to suppress the banner (auto-set per session)

---

Scheduler

A background daemon starts automatically on the first rana command. Every 5 minutes it:

1. Runs claude --print "/usage" --output-format json for each Claude Code account
2. Parses token/cost usage for the current billing period
3. Ranks accounts by remaining budget headroom
4. Writes the recommendation to ~/.rana/scheduler-state.json

rana switch claude reads this file to pick the best account instantly.

---

Troubleshooting

claude binary not found

Install Claude Code: https://claude.ai/download

Account auth path not found

rana switch claude --force   # reconfigure inline

Dashboard won't start

rana dash --port 4243        # try a different port

No agents showing in rana agent list

rana reads ~/.claude/projects/**/sessions/*.json. Start Claude Code and create a session first.

Scheduler not updating

Check if the scheduler is running:

cat ~/.rana/scheduler.pid

Kill and restart:

kill $(cat ~/.rana/scheduler.pid)
rana switch claude            # restarts automatically

---

Development

npm run dev          # run with tsx (no build step)
npm run build        # compile to dist/
npm run typecheck    # type-check without emitting
npm link             # install globally from source

License

MIT