arthai-marketplace

Getting Started

New here? This guide takes you from nothing to a working toolkit in ~10 minutes (Steps 1–6), then observability (Step 7, optional), calibration (Step 8), and a fresh session (Step 9).

No toolkit — just the arth CLI? Do Steps 1–2, then Installing the Arth CLI. It gives you telemetry, Explain, and the Cloud Orchestrator from a terminal without the Claude Code toolkit.

Already installed? Skip the walkthrough — update via the FAQ update flow, connect another repo to observability via the Arth Intelligence guide, or fully remove it via the Uninstall guide.

Prerequisites

Step 1: Get a license key and repo access

Email productive@getarth.ai with your GitHub username to request a license key.

You’ll receive:

Accept the GitHub invite before continuing — Step 3 requires repo access.

Just want the no-toolkit CLI? If you’re not using the Claude Code toolkit and only want the arth command (telemetry + Explain + Cloud Orchestrator from a terminal), do Steps 1–2 above, then jump straight to Installing the Arth CLI — you can skip the toolkit steps (3–7).

Step 2: Activate your key

Run this in your terminal (not inside Claude Code):

npx arthai-activate ARTH-XXXX-XXXX-XXXX-XXXX

This stores your key at ~/.arthai/license. You only need to do this once.

Step 3: Add the plugin marketplace

Inside Claude Code:

/plugin marketplace add ArthTech-AI/arthai-marketplace

Step 4: Choose and install a bundle

Start with prime — the everything bundle. Includes all agents, skills, and hooks:

/plugin install prime@arthai

If you want a smaller, focused bundle instead, see the plugin catalog for all available bundles.

Step 5: Enable auto-updates

Run /plugin, open the Marketplaces tab, select arthai, and choose Enable auto-update. This keeps your toolkit up to date automatically — new agents, skills, and bug fixes land without manual intervention.

Step 6: Reload and verify

/reload-plugins

Then fully quit and reopen Claude Code. A running session loads its command list at startup, so a newly added command (e.g. /cloud-setup after an update) won’t appear from /reload-plugins alone — only a full restart (quit the app/CLI completely, not /clear) rebuilds the command set. This is the most common reason a freshly installed skill “isn’t there.”

Step 7: Enable observability (optional)

You can skip this step and jump to Step 8: Calibrate. The toolkit works without observability. Come back here whenever you want a dashboard view of what Claude Code is doing — sessions, tool calls, agent spawns, cost.

New to this? Start with the Arth Intelligence guide — what the dashboard shows, why you’d want it, and what data stays on your machine. This step is the detailed install walkthrough.

⚠️ Experimental — limited preview. Observability is in active development. Expect rough edges, breaking changes between releases, and gaps in coverage. Feedback welcome at productive@getarth.ai.

See what Claude Code did — every tool call, agent spawn, and workflow phase visualized in a dashboard.

Two telemetry streams, both required for full data:

/otel-setup turns both on for you. Without CLAUDE_CODE_ENABLE_TELEMETRY=1, the dashboard’s cost and token columns stay empty — that’s the most common “why is my dashboard half-broken?” question.

Prerequisites

7a: Install the sentinel bundle (skip if you installed prime)

Inside Claude Code:

/plugin install sentinel@arthai

This adds the OTEL tracing hook and the /otel-setup skill to your project.

If you already have sentinel installed, update it (or rely on auto-update from Step 5):

/plugin marketplace update arthai
/plugin uninstall sentinel@arthai
/plugin install sentinel@arthai
/reload-plugins

7b: Restart Claude Code

Close and reopen Claude Code (or start a new session). When the session starts, you’ll see this message:

OTEL_SETUP_REQUIRED: Observability is installed but not configured.
Run /otel-setup now.

7c: Run /otel-setup

No toolkit? Use the Arth CLI instead. Everything in Step 7 is the toolkit path. If you’re not running the Claude Code toolkit, install the Arth CLI (one line, below) and run arth otel-setup — it stands up the identical stack (db + dashboard on :3100 + engine on :4319) and writes the same global native-OTEL env, no toolkit required. See Installing the Arth CLI just below, then continue to Step 8 / arth cloud-setup. If you later install the toolkit, /otel-setup detects this stack and only adds toolkit attribution.

Installing the Arth CLI (no toolkit)

The Arth CLI ships through the private Arth distribution repo — install is gated by the same GitHub access you already have (the repo invite + your ARTH_GITHUB_TOKEN); no public package. Requires Node.js 22+.

Need a token? ARTH_GITHUB_TOKEN is a GitHub fine-grained PAT with Contents: Read on ArthTech-AI/arthai-marketplace — the same one the orchestrator uses. Create it the way described in the Cloud Orchestrator prerequisites (github.com → Settings → Developer settings → Fine-grained tokens → Resource owner ArthTech-AI, repo arthai-marketplace, Contents: Read-only). Already use the gh CLI and it can read that repo? The installer will use gh auth token automatically — no need to set the variable.

# 1) Make sure your GitHub token (read access to ArthTech-AI/arthai-marketplace) is set:
export ARTH_GITHUB_TOKEN=github_pat_...     # or have the `gh` CLI logged in

# 2) Install the Arth CLI (downloads the self-contained binary onto your PATH).
#    Private repo → use the GitHub contents API with the raw accept header:
curl -fsSL -H "Authorization: Bearer $ARTH_GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.raw" \
  https://api.github.com/repos/ArthTech-AI/arthai-marketplace/contents/cli/install.sh | sh

# 3) Verify it's on your PATH:
arth --help

Without read access to the repo the download 404s — that’s the access gate. The installer puts arth in ~/.local/bin — if arth --help says “command not found”, add that to your PATH: export PATH="$HOME/.local/bin:$PATH" (the installer prints this hint too). It also warns (but doesn’t block) if you haven’t activated a license yet: you only need the Arth license later, for arth cloud-setup → the experimental Cloud Orchestrator. Then:

arth otel-setup     # telemetry stack — no license needed
arth cloud-setup    # Explain this session + the experimental Cloud Orchestrator

Updating the CLI later: re-run the same install one-liner — it overwrites arth with the latest published build and re-verifies the checksum.

Type:

/otel-setup

The skill asks how you want to set up. Pick “Local” (option 2).

The skill then does everything for you automatically:

  1. Checks Docker is running on your machine
  2. Creates a configuration file at ~/.arthai/docker-compose.yml
  3. Downloads the Arth Intelligence Docker image (first time takes 1-2 minutes)
  4. Starts the engine on :4319 (receives traces) + dashboard on :3100 (shows traces) + database (stores traces) + Watchtower (auto-updates the engine image daily)
  5. Waits until everything is healthy
  6. Writes environment variables — including CLAUDE_CODE_ENABLE_TELEMETRY=1 — to your global ~/.claude/settings.json by default (so every project on this machine emits telemetry; nothing is committed to your repos). If you pick the “this project only” scope instead, they go to that repo’s .claude/settings.local.json.
  7. Creates a marker file so it doesn’t ask you again

It asks two quick questions along the way — env-var scope (global vs this-project-only) and whether to keep session auto-tagging on — then runs unattended until done.

7d: Restart Claude Code (mandatory)

Close and reopen Claude Code so it picks up the new env block from ~/.claude/settings.json (or the repo’s .claude/settings.local.json if you chose project-only scope). Without this restart, the env vars aren’t loaded and traces won’t flow.

7e: Verify it’s working

You’ve just restarted Claude Code. The dashboard exists but is empty — there’s no data yet because you haven’t done anything yet. Walk through these in order:

  1. Open the dashboard in your browser. Go to http://localhost:3100. You should see the Arth Intelligence Hub — a project/session list with an Experiments page in the sidebar. The Hub will probably be empty at this point — that’s expected, you haven’t run anything yet.

    If the page doesn’t load at all, the Docker stack may not be up. Run:

    docker ps

    You should see three containers — arthai-intelligence, arthai-db, arthai-watchtower. If any are missing:

    docker compose -f ~/.arthai/docker-compose.yml up -d
  2. Generate some activity in Claude Code. Switch back to Claude Code and run any prompt — even something trivial: 
    what's in package.json?

    Or:

    /onboard

    The toolkit’s OTEL hook emits trace spans for every prompt, tool call, agent spawn, and stop event. Native OTEL emits cost and token data alongside.

  3. Refresh the dashboard. Your session should appear in the Sessions list with a recent timestamp. If nothing appears after ~10 seconds, the engine may not be receiving traces. Check engine health: 
    curl -s http://localhost:4319/api/health | jq .

    Expect a JSON response containing "ok":true. If it fails, check logs:

    docker logs arthai-intelligence | tail -50

  4. Click into your session. You should see a waterfall of spans — your prompt, the tool calls Claude Code made, any agent spawns, etc. Each span shows duration and metadata.

  5. Confirm cost columns are populated. Look at the cost / token columns in the trace.
    • If they show values (e.g. $0.0023, 1,847 tokens) → native OTEL is flowing. You’re done.
    • If they show — or are empty → only the toolkit hook is on. Native OTEL needs CLAUDE_CODE_ENABLE_TELEMETRY=1. Verify: 
      grep CLAUDE_CODE_ENABLE_TELEMETRY ~/.claude/settings.json
# or, if you chose project-only scope: grep CLAUDE_CODE_ENABLE_TELEMETRY .claude/settings.local.json
# should print: "CLAUDE_CODE_ENABLE_TELEMETRY": "1"

      If missing, re-run /otel-setup, pick Local again, then restart Claude Code.

If all 5 steps work — observability is working end-to-end. Future Claude Code sessions automatically send traces to http://localhost:3100. You don’t need to do anything else.

7f: Capture a baseline — observer-only mode (optional)

Sometimes you want to know: what does Claude Code do on its own, vs. what changes when the toolkit is active? Maybe you’re evaluating whether to keep the toolkit on for a particular workflow, or you want to debug a behavior and need to isolate “is this the toolkit or is this Claude itself?”

Observer-only mode is for that. It keeps the OTEL hook emitting telemetry (so you still see the run in the dashboard), but suppresses every toolkit-specific side effect:

export OTEL_OBSERVE_ONLY=true

Then launch Claude Code as you normally would. That session’s spans land in the dashboard exactly like a regular run, but:

To clear it, unset OTEL_OBSERVE_ONLY (or just open a new shell). It only applies to sessions started while the env var is set.

Typical A/B workflow:

  1. Run a normal Claude Code session — do something representative (e.g., ask /onboard to brief you, then ask a follow-up).
  2. Open a new terminal, export OTEL_OBSERVE_ONLY=true, and launch Claude Code again. Run the same prompts.
  3. In the dashboard, find the two sessions side-by-side. The toolkit-on run has skill attribution (skill.name = "onboard" on the tool spans); the observer run does not. Compare the trace shapes, durations, and span counts.

That diff is the toolkit’s contribution to your workflow.

Precedence — which env wins:

Set Behavior
Nothing Default — toolkit on, telemetry on
OTEL_OBSERVE_ONLY=true Telemetry on, toolkit side effects off (this section)
OTEL_DISABLED=true Telemetry off, toolkit off (overrides observer mode)

Filtering observer runs in the dashboard UI ships in a future release. Until then, the arth.observe_only attribute is carried on every span of an observer run — the runs appear in the dashboard alongside normal ones.

7f.1: Compare baseline vs toolkit in the arth dashboard

Once you’ve captured a baseline run AND a regular toolkit run, the arth dashboard’s /experiments page renders them side-by-side across cost, tokens, calls, cache hit rate, lines edited, and active time.

Auto-tagging (default ON for both modes):

Every session you run automatically gets an arth.experiment label so it shows up in /experiments dropdowns without you having to set anything before each launch. The label format makes baseline vs toolkit easy to scan:

Mode Label format Generated by
no-toolkit baseline (just claude, no plugin) auto-baseline-<git-branch>-<first-prompt-slug>-<unix> Engine’s session-watcher (reads CC’s session JSONL)
toolkit-on session (prime@arthai installed) auto-toolkit-<git-branch>-<unix> Toolkit’s OTEL hook (hooks/otel-telemetry.sh)

Example after running the same task twice:

auto-baseline-main-debug-login-failure-1715890123
auto-toolkit-main-1715891456

Pick one as left, the other as right, click Compare.

Quick walkthrough — zero-config path:

  1. Run baseline first (no env vars, no aliases). Just claude in your project.
  2. Run toolkit second (still no env vars). Just claude again — the toolkit auto-installs the hook.
  3. Open the dashboard at http://localhost:3100/experiments. Both runs are already in the dropdowns.
  4. Pick left = baseline, right = toolkit, click Compare.

Custom labels (override auto-tag):

If you want a specific human-readable label instead of the auto one, set arth.experiment before launching — your value wins:

export OTEL_RESOURCE_ATTRIBUTES="$OTEL_RESOURCE_ATTRIBUTES,arth.experiment=prepme-credit-bug-baseline"
claude

Turn auto-tagging OFF:

Set ARTH_AUTO_EXPERIMENT_DISABLED=1 — same env var honored by both modes:

/otel-setup asks you about this at install time — you can flip it then or at any point later.

Mid-session annotations — type /marker "spike here" inside any session. An amber ◆ glyph appears on the dashboard’s DAG timeline within ~5s. From the dashboard, you can also click Drop marker on any session detail page. Export filtered slices — /arth logs export --since 1h from inside Claude Code, OR use the dashboard sidebar’s “Download diagnostic bundle”. Filter by experiment, marker, session ID, and time range — all AND-compose.

The Arth Intelligence guide has the condensed version of this comparison flow.

7g: What survives a reboot

After you reboot your Mac (or restart Docker Desktop), here’s what comes back automatically and what doesn’t:

Layer Survives reboot? Why
Env vars in .claude/settings.local.json ✅ Yes File on disk — Claude Code reads it on every session start
~/.arthai/docker-compose.yml ✅ Yes File on disk
arthai_data volume (your traces, scores, patterns) ✅ Yes Docker named volume — persistent across container restarts and reboots
Engine container (arthai-intelligence) ✅ Yes — for current compose templates Compose template sets restart: unless-stopped. If docker inspect shows RestartPolicy: no, your install predates this — one-time migration below.
Postgres container (arthai-db) ✅ Yes — same caveat Same — depends on compose template having restart: unless-stopped.
Watchtower auto-updater ✅ Yes Already had restart: unless-stopped in older compose files.
Docker Desktop itself ⚠️ Depends on YOU Docker Desktop has a per-user “Start Docker Desktop when you log in” toggle (Settings → General). If it’s off, nothing comes back until you launch Docker Desktop manually. We can’t set this for you — it’s an OS-level user preference.

Quick verify after a reboot:

docker ps --filter 'name=arthai'
# Should show 3 running containers: arthai-intelligence, arthai-db, arthai-watchtower

If any are missing, start them:

docker compose -f ~/.arthai/docker-compose.yml up -d

Migration for older installs (containers showing RestartPolicy: no):

If docker inspect shows your containers have RestartPolicy: no, run this one-liner — no data loss, no re-setup:

docker update --restart unless-stopped arthai-db arthai-intelligence

Or re-run /otel-setup and pick Local — the new compose template will overwrite ~/.arthai/docker-compose.yml with the right policy.

Opting out of auto-restart:

If you’d rather start Arth Intelligence manually each session (e.g., to save resources when not coding):

docker update --restart no arthai-db arthai-intelligence arthai-watchtower

You’ll need to docker compose -f ~/.arthai/docker-compose.yml up -d whenever you want the dashboard back.

7h: Updating Arth Intelligence

There are three things that can update independently. Each has its own update path. None of them touch your trace data — your sessions, scores, and patterns live in the arthai_data Docker volume and are preserved across all updates.

Layer What updates it How often
The container image (arthai/intelligence) Watchtower sidecar — pulls + restarts the container Daily, automatic
The skill on disk (/otel-setup) Standard plugin update (auto-update, or reinstall the bundle) When you update plugins
Your local compose file (~/.arthai/docker-compose.yml) Re-running /otel-setup — overwrites with the latest template Only when you run the skill again

The container image — two ways

Automatic (default). A watchtower sidecar shipped in the compose template checks once a day, pulls the latest arthai/intelligence image, and restarts only that container. You don’t need to do anything. To verify it’s running:

docker ps --filter name=arthai-watchtower

Manual — force an update right now. Run the hosted update script:

curl -fsSL https://arthtech-ai.github.io/arthai-marketplace/scripts/update.sh | sh

Or paste the two commands directly if you’d rather not pipe to shell:

docker compose -f ~/.arthai/docker-compose.yml pull
docker compose -f ~/.arthai/docker-compose.yml up -d

Both do the same thing — pull the latest image and recreate the container against it. The named volume arthai_data is left untouched.

To opt out of auto-updates:

docker stop arthai-watchtower
docker rm arthai-watchtower

You’ll then need to update manually using the script above whenever you want a new version.

The skill — when we ship a new /otel-setup

/plugin marketplace update arthai
/plugin uninstall sentinel@arthai
/plugin install sentinel@arthai
/reload-plugins

If that doesn’t pick up the change, fall back to the marketplace remove + re-add flow shown in the FAQ.

The compose file — only matters if the template changes

If a sentinel release changes the compose template (e.g. adds a new service), you’ll need to re-run /otel-setup to regenerate ~/.arthai/docker-compose.yml with the new content. Re-running the skill is safe — it overwrites the compose file but never touches the arthai_data volume.

The one thing that destroys data

docker compose -f ~/.arthai/docker-compose.yml down -v   # ← DON'T DO THIS

The -v (--volumes) flag drops the arthai_data volume and erases every session, score, and pattern. Plain docker compose down (without -v) stops the containers but keeps the data — that’s safe and reversible. Only use down -v if you intentionally want to wipe everything and start fresh.

What you see in the dashboard

Troubleshooting

Problem Fix
/otel-setup says “Docker is not running” Open Docker Desktop, wait for it to start, then re-run /otel-setup
Dashboard at localhost:3100 shows nothing Traces stream live — run any prompt in Claude Code, then refresh the dashboard page.
Dashboard doesn’t load at all Check Docker is running: docker ps should show arthai-intelligence and arthai-db containers. If not, run: docker compose -f ~/.arthai/docker-compose.yml up -d
Traces stop appearing after a restart Run source ~/.zshrc to reload environment variables, or check that Docker containers are still running: docker ps
Want to stop the dashboard Run: docker compose -f ~/.arthai/docker-compose.yml down
Want to restart the dashboard Run: docker compose -f ~/.arthai/docker-compose.yml up -d
Want to update to the latest version See 7h: Updating Arth Intelligence — auto-updates daily, force now with update.sh
Want to remove everything Run: docker compose -f ~/.arthai/docker-compose.yml down -v (this deletes all trace data)

7i: Enable the dashboard’s AI features (optional)

/otel-setup (above) is telemetry-only. On top of it there are two separate optional features — don’t conflate them:

Not sure which keys you need? See Configuration → Keys at a glance for a one-table summary. Short version: telemetry needs none, Explain on a local model (Ollama / LM Studio + qwen) needs none, a cloud Explain model needs that provider’s key, and only the experimental orchestrator needs a Claude key + GitHub token + license.

A. “Explain this session” — a grounded AI summary. NOT experimental. You can turn this on without the experimental orchestrator. It’s offered at the end of /otel-setup (or arth otel-setup), and also by /cloud-setup. Pick any provider — including free local models:

Provider What you provide
Anthropic / OpenAI / Gemini / Bedrock that provider’s API key
Ollama (local, free) host (default http://host.docker.internal:11434)
LM Studio (local, free) host (default http://host.docker.internal:1234) — the loaded model (e.g. qwen) is auto-detected

New user: just answer “yes” when /otel-setup offers Explain and pick a provider. Existing user (set up before this): re-run /otel-setup (or /cloud-setup) and opt into Explain — your key is added to ~/.arthai/.env and survives image updates. Local-model step-by-step: Configuration → Local models.

B. Cloud Orchestrator — experimental, Claude-only. Point Arth at a Git repo and watch it calibrate or plan a feature live. Off until you opt in via /cloud-setup (toolkit) or arth cloud-setup (CLI):

/cloud-setup        # in Claude Code (toolkit)
arth cloud-setup    # from a terminal (Arth CLI — no toolkit needed)

The sandbox runs Claude only (for now), so you’ll need an ANTHROPIC_API_KEY even if you set Explain to a non-Claude provider (both keys are kept). Plus your license (auto-read from ~/.arthai/license if you ran npx arthai-activate) and a GitHub fine-grained token with read access to ArthTech-AI/arthai-marketplace. See the Cloud Orchestrator guide for how to create the token + the full walkthrough.

Step 8: Calibrate your project

On first use in a project, run:

/calibrate

This scans your codebase and configures the toolkit to match your project’s patterns, conventions, and tech stack. It also builds a knowledge graph — a ranked index of your project’s conventions, domain rules, and patterns that workflows like /fix query automatically to get the most relevant context for each task. The graph auto-rebuilds whenever your knowledge base changes.

Want it cheaper? Calibrate’s sub-agents are already Haiku/Sonnet — the only Opus cost is the Claude Code session driving it (your "model" setting, not the toolkit). Run /model sonnet before /calibrate for a no-Opus pass. Details: /calibrate → Cost & running it cheaply.

Step 9: Start a new Claude Code session

Restart your Claude Code session so the knowledge graph gets built and the OTEL env block from Step 7 is picked up. Then:

/onboard                    # prioritized briefing on what to work on
/planning my-feature        # start building with the toolkit

You’re ready.

After installing and calibrating:

/onboard                    # get a briefing on your project
/planning my-first-feature  # try the planning workflow
/implement my-first-feature # spawn the team that builds it
/qa                         # commit-mode QA on the diff
/pr                         # create the PR

If you’re not building something new, two good explorations:

/tech-debt                  # survey, prioritize, and propose plans for tech debt
/perf <scope>               # cross-functional performance pass

Common skills — cheat sheet

The full list of every skill in your installed bundles is at skills-reference.md. The most common ones grouped by what you’re doing:

You want to… Use
Onboard / decide what to work on /onboard, /welcome, /wizard
Plan and build a feature /planning (includes design spec HTML by default), /implement, /qa, /pr
Fix a bug formally /fix <description\|#issue>
Ship code /precheck, /qa, /revert-check, /pr (or /ship for the one-shot)
Review a PR /review-pr <#N>
Audit code health /tech-debt, /perf
Generate or audit docs /docs <audit\|write\|check>
Repair a broken pipeline /incident, /ci-fix, /sre
Restart local servers /restart [service]
Deploy /deploy <local\|staging\|...>, /deploy-ios
Schedule recurring agents /schedule-routine, /autopilot
Manage GitHub issues /issue <title>, /issue list, /issue close #N
Share a plan or strategy /share <plan> --format md\|slack\|twitter
Generate from templates /templates <type> <topic>

Bundle-specific skills (consulting, design, etc.) live in their respective bundles — install the bundle to surface them. See the plugin catalog.

Using Cowork Dispatch (tweet → pipeline)

Partner installs only. This feature requires access to the claude-agents source repo, which standard plugin customers don’t have. Skip this section unless Arth AI has given you source access.

Cowork is Anthropic’s mobile companion app for Claude. The prime bundle includes a Cowork Dispatch skill: paste a tweet URL in Cowork and it automatically queues /monitor-tweet on your desktop Claude Code.

Additional requirement: the Cowork skill dispatches to ~/.claude-agents on your Mac — a source-repo clone. You need both:

# 1. Plugin install (above) — surfaces the skill in Cowork
# 2. Clone the toolkit to ~/.claude-agents — provides /monitor-tweet on desktop
git clone git@github.com:ArthTech-AI/claude-agents.git ~/.claude-agents
~/.claude-agents/install.sh --key ARTH-XXXX-XXXX-XXXX-XXXX ~/.claude-agents

Without the clone, the Cowork skill fires but the desktop pipeline has no /monitor-tweet to run.

Knowledge graph

When you run /calibrate, the toolkit builds a knowledge graph from your project’s knowledge base (.claude/knowledge/). This is a ranked index of your conventions, domain rules, patterns, and vocabulary that agents query automatically.

How it works:

  1. /calibrate scans your codebase and populates .claude/knowledge/shared/ with conventions, domain rules, patterns, and vocabulary
  2. The knowledge graph indexes these files into a fast-lookup graph (.claude/knowledge/graph/)
  3. When any skill runs (/fix, /planning, /implement, /qa, etc.), it queries the graph to pull in only the most relevant context — instead of loading every knowledge file in full
  4. The graph auto-rebuilds whenever your knowledge base changes

What this means for you:

Next steps