Arko for Claude Code

Check changed code, understand a finding, and review a repair without leaving your conversation.

Install

Run this in the project you want to check:

claude mcp add arko -- npx -y arko-mcp@latest

Start Claude Code in that project and allow the Arko connection. Arko installs the local /arko command when the local connection starts in a recognised Git project. Existing custom commands are preserved. On a host that does not reload commands, restart the session. If automatic command installation is unavailable, run npx -y arko-mcp@latest init in the project, then restart Claude Code. The registration command alone does not install slash commands until the local server has started.

Sign in with your work email when prompted. For a manual sign-in:

npx -y arko-mcp@latest login --email [email protected]

Use /arko. It checks changed code and shows the gate result, the most useful findings, and the next action. A result covers the code actually analysed; missing or incomplete analysis is not a pass.

| Command | What happens | | --- | --- | | /arko | Check staged, unstaged and untracked changes. | | /arko fix | Review a repair plan, approve the changes, verify the fix, and obtain a fresh gate result. | | /arko explain | Explain the last finding's impact and first action. | | /arko details | Show the last result in detail without starting another scan. | | /arko setup | Choose optional project checks and guidance. |

A repair requires your approval. Verification uses full current file contents; skipped, unreadable or omitted files do not prove a fix. A fresh completed scan supplies the new gate.

Optional setup

/arko setup offers a blocking severity (critical, high or medium), automatic checks after Edit/Write, and a short Arko section in CLAUDE.md. Automatic checks and guidance are off until you choose them. Your organisation's stricter rules still apply.

Preview and apply only your chosen options:

npx -y arko-mcp@latest setup --threshold high --dry-run
npx -y arko-mcp@latest setup --threshold high

Use --edit-hook or --claude-guidance only when you want those additions. Use --no-edit-hook to remove Arko's own edit handler. Existing settings, permissions, unrelated hooks and instructions are preserved. Replaced configuration files have a private backup in the system temporary directory. An existing custom Arko command or instruction section is left for you to review.

To dismiss the reminder for just this project, choose /arko setup dismiss or run:

npx -y arko-mcp@latest setup --dismiss

The optional Edit/Write hook invokes the same gate --changed command. A passing completed check adds its verdict to the conversation. Findings or an incomplete check return blocking feedback to the assistant. Parallel edits are coalesced; a queued check is not a pass. The hook runs after the edit, so it cannot undo the edit or replace a CI merge check. An organisation's Claude Code restrictions can prevent local hooks or commands from loading. See Claude Code's hook contract and local command discovery.

Terminal and pipeline checks

Start with a local preview:

npx -y arko-mcp@latest scan ./module --dry-run --manifest ./analysis-manifest.json
npx -y arko-mcp@latest scan ./module
npx -y arko-mcp@latest gate --staged

A dry run sends no source. The manifest records selected paths, ranges, exclusions and replacements. Account-specific analysis scope limits still apply to scans and verification.

scan prints the dependency table as soon as it is ready and waits up to 15 minutes (ARKO_SCAN_WAIT_MS) for the code analysis, which takes several minutes on a real project. If it stops waiting it exits 3 (still analysing — not a failure) and names the scan; fetch that scan's report later, without starting another scan:

npx -y arko-mcp@latest results <scan-id>

results (alias attach) waits for a scan that is still analysing, printing a heartbeat every 30 seconds, then prints the same report a completed scan prints: the gate line, the code findings by category, dependencies, licences and the visual report path. Re-running scan while a scan of the same project is still running attaches to it instead of starting a second one.

For a pipeline, store an Arko API token in your CI secret store as ARKO_API_TOKEN. It is sent as X-Arko-Token and takes precedence over ARKO_TOKEN. Do not put either token into repository files. Use whoami to check the current session, and logout to remove it.

gate exits 0 for passing or explicitly warn-only completed results; blocking findings and incomplete analysis exit 2. A deliberately disabled legacy gate reports GATE: DISABLED, not a pass. --warn does not make missing analysis pass. ARKO_GATE or --min-severity override the project preference; central rules can require a stricter threshold. No detection rules or server settings are changed by setup.

Run on a schedule from your own machine

No CI? Arko can scan a folder on a cadence from your laptop or workstation. Sign in once, then:

npx -y arko-mcp@latest login --email [email protected]
npx -y arko-mcp@latest schedule add --path ~/src/my-service --every 1d --at 09:00 --name my-service
npx -y arko-mcp@latest schedule list
npx -y arko-mcp@latest schedule run my-service      # run it once now
npx -y arko-mcp@latest schedule remove my-service

--every takes 1h, 6h, 1d, 7d or 14d; --at HH:MM sets the local time for daily and longer cadences. Add --estate to scan a multi-module folder and --project <name> to name the project in the Console. Names are kebab-case.

add installs a per-user job (macOS: a LaunchAgent, ~/Library/LaunchAgents/io.arko.scan.<name>.plist; Linux: a tagged crontab line; Windows: a Scheduled Task). The job is just npx -y arko-mcp@latest schedule run <name>; the folder and options live in ~/.arko/schedules/<name>.json, and each run appends npx -y arko-mcp@latest scan <folder> --json output to ~/.arko/schedules/<name>.log. The job carries no token: each run uses your cached sign-in and refreshes it silently. Sign in at least every 30 days; if the session has lapsed the run logs "Not signed in" and exits 1 without opening a browser. The machine must be awake and online at the scheduled time. Re-running add with the same name replaces the job.

Other editors

The same Arko connection can be configured by an MCP-compatible editor. The /arko local command and Edit/Write hook are Claude Code features; other editors use their own command and approval surfaces. Their Arko checks use the same account rules.

Read the saved dependency inventory

After a scan, Arko reads the server inventory, including available transitive dependencies, versions, licences and dependency relationships. Background resolution may still be running; the output labels that snapshot and provides its scan ID. To refresh without uploading source or starting another scan:

arko-mcp sbom --scan-id <scan-id>
arko-mcp sbom . --project <project> --branch <branch> --json

With no branch supplied, Arko checks the existing own-user project reader for the latest scan. An explicit branch uses a locally remembered scan receipt for the same account, API, project and branch, retained for seven days; it never falls back to another branch. Every refresh is authorised by the server. If no server inventory is available, local results are labelled declared dependencies; they are not a complete dependency tree or an advisory assessment. Display tables are limited for readability; the structured output and saved CycloneDX snapshot retain the returned rows and relationships. A failed or unfinished resolution never appears as a complete graph.

Agents can use the read-only arko_get_sbom tool with a scan ID, or the same project and branch, to refresh that inventory. Optional manifest input is parsed locally only.

Fetch a scan's findings later

When a scan tool stops waiting it ends with Analysis still running (scan <id>). Call arko_scan_results with this scan_id to fetch the findings. The read-only arko_scan_results tool (input: scan_id, optional project_name) waits for that scan if needed and returns the same report a completed scan returns — gate line first — without starting another scan. It is the agent's equivalent of arko-mcp results <scan-id>.