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 run

# Open the web dashboard
rana dash

# Watch your agents in real time
rana agent watch

Commands

rana run

Select an account and launch Claude Code or Codex directly.

| Command | Description | |---|---| | rana run | Open the interactive account selector and launch the chosen account |

Claude launches with --dangerously-skip-permissions. Codex launches with --dangerously-bypass-approvals-and-sandbox.

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 scheduler

Inspect and manage the background scheduler daemon.

| Command | Description | |---|---| | rana scheduler status | Show PID, uptime, last heartbeat, active account, and reason | | rana scheduler status --json | Print the same status as JSON | | rana scheduler stop | Send SIGTERM and confirm shutdown | | rana scheduler restart | Stop then start the daemon | | rana scheduler logs | Tail ~/.rana/logs/scheduler.log |

Example:

Scheduler  running  (pid 12345, up 2h 14m)
Last tick  3m ago
Active     work-account  (42% of 5h window used, 58% remaining)
Reason     Least used: 42.0% of 5h window

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. Use rana scheduler status to inspect the daemon without reading runtime files directly.

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

Inspect or restart it directly:

rana scheduler status
rana scheduler restart

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