argonex — Argonex CLI worker

Polls the Argonex server for work, runs the agent loop locally against your codebase using your BYOK LLM key, ships structured results back.

Two property guarantees:

1. Your code never reaches Argonex servers. The local agent loop talks directly to your LLM provider (Anthropic / OpenAI / Google) using your own key. Only structured verdicts (e.g. "gap X is shipped, evidence: file paths") get POSTed back.
2. Argonex's prompts never touch your disk. Prompt bodies are HMAC- signed with your CLI bearer token (no global shared secret) and held in memory only — never cached, never written.

Quick start

# 1. Install (one-time)
npm install -g argonex-cli       # or: cd cli/thin && npm install && npm link

# 2. Log in (one-time)
argonex login                      # prompts for token + (optionally) API URL

# 3. Pick which project you're working on (one-time, sticky)
argonex projects                   # list projects in your org
argonex use my-product             # pin one by slug

# 4. Run, from inside the project's repo
cd ~/code/my-product
export ANTHROPIC_API_KEY=sk-ant-…  # or OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY
argonex run                        # polls indefinitely; ^C to stop

After the first three steps, day-to-day usage is just cd + argonex run. Switching projects is argonex use <other-slug>.

Commands

| Command | What it does | |--------------------|---| | argonex login | Prompts for your CLI token + API URL, validates against the server, persists to ~/.argonex/config.json (chmod 0600). | | argonex projects | Lists projects in your org. Marks the currently pinned one. | | argonex use <slug> | Pins a project. Required before argonex run. Validates the slug against the server's project list. | | argonex run | Polls the server for work in your pinned project. Loops until ^C. | | argonex whoami | Prints the org + token + pinned project from your saved config. Works offline. | | argonex logout | Removes ~/.argonex/config.json. |

Each accepts --help for command-specific options.

How argonex run works

1. Reads ~/.argonex/config.json for your token + API URL.
2. Detects the current git repo's origin remote so the server can register your codebase against the pinned project (one-time, only when blank server-side).
3. Startup handshake — POSTs to /api/v1/cli/sessions/ensure to make sure there's an /intel run in flight for the project. If none exists, the server creates one and returns the run id.
4. Enters the polling loop:
   • Polls GET /api/v1/cli/work_bundles/next for a signed bundle.
   • 200 → verifies HMAC (bearer token = HMAC key), runs the agent loop using your BYOK LLM provider with primitives sandboxed to the current directory, POSTs structured results back.
   • 204 → fetches the run's status from GET /api/v1/cli/runs/:id/status and prints a one-line idle summary so you can see which server-side phase is currently running and how many phases remain.
5. Auto-exits with a final summary when the pipeline reaches a terminal state (completed / failed / cancelled), so you can leave the worker running and walk away.

Phases that need this CLI

The pipeline has 13 phases. Two need your local codebase:

• scanner — runs early, captures your tech stack + design tokens
  • import aliases for the POC builder later
• check_shipped — runs late (after gaps are identified), scans your repo to mark gaps you've already shipped

Between them, ~5 phases run server-side (discover → analyze → reviews → compare → gaps) — your CLI sits idle and shows progress. Don't kill it after scanner finishes — the pipeline will park itself indefinitely waiting for you to come back at check_shipped.

Tool surface (the entire CLI capability)

| Tool | Reads | Bounds | |-------------|-----------------------|---------------------------------------------------------| | file_read | one UTF-8 file | 1 MiB; refuses .env/.pem/secrets, refuses non-text | | file_list | one directory | 500 entries; skips node_modules, .git, dist, etc. | | grep | recursive regex | 200 matches; skips heavyweight dirs | | kv_put | in-memory cache | per-bundle only; cleared between phases | | kv_get | in-memory cache | per-bundle only |

No write tools. No shell exec. No network calls (other than to your LLM provider via the SDK). Every primitive routes through the sandbox boundary check (safeResolve in src/sandbox/paths.ts).

LLM provider selection

First env var present wins, in this order:

1. ANTHROPIC_API_KEY (preferred — Argonex prompts are tuned for Claude)
2. OPENAI_API_KEY (model name auto-mapped: haiku → gpt-4o-mini)
3. GOOGLE_GENERATIVE_AI_API_KEY (haiku → gemini-2.0-flash)

If none are set, argonex run exits with status 6 + a clear error.

Local development end-to-end

For dev/CI loops against a local Argonex stack:

# Shell A — full stack on localhost:3100
cd <argonex-repo>
bin/dev

# Shell B — prime the test fixtures
[email protected] bin/rails runner bin/cli-thin-bootstrap

# Shell C — run the worker
cd ~/code/my-product
export ANTHROPIC_API_KEY=sk-ant-…
argonex login --api-url http://localhost:3100
argonex run

The bootstrap script primes a project + parked run + open gaps in your real org, then prints which existing CLI tokens you can use for argonex login. No new tokens minted.

Exit codes

0  ok (worked, or 204 = nothing to do)
2  config error (not logged in, missing flag)
3  signature mismatch — refuses to execute (token / server mismatch)
4  API error (4xx/5xx from server)
5  sandbox violation (or invalid source path)
6  agent loop error (LLM call failed, bad JSON, missing BYOK key)
7  results POST failed
130 SIGINT (Ctrl+C)

Tests

npm test            # 42 vitest cases
npm run typecheck

Limitations (v1)

• No log streaming back to server. Agent output lives in your terminal only.
• Distributed as a Node script, not a single binary. pkg / bun build --compile packaging is a follow-up.
• In-memory KV resets per bundle. No cross-bundle caching yet (e.g. scanner output isn't auto-fed to check_shipped).
• Prompts tuned for Claude. GPT-4 / Gemini work but quality may be lower until per-provider prompt variants land.
• No heartbeat / cancellation. A long-running bundle keeps going even if the server cancels the run; result POST will then 422.