CLI Reference¶

All JSAT commands start with jsat. Run jsat --help or jsat <command> --help for any command.

1. Core Commands¶

`jsat index`¶

Build or update the codebase graph.

jsat index [PATH] [OPTIONS]

Argument / Flag	Default	Description
`PATH`	repo root	Directory to index
`--branch`, `-b`	`HEAD`	Git branch to index
`--force`, `-f`	false	Full re-index — ignore incremental manifest
`--languages`, `-l`	auto	Comma-separated list, e.g. `python,go`
`--incremental/--full`	incremental	Use incremental or full index strategy
`--watch`, `-w`	false	Re-index on file change (requires `entr`: `brew install entr`)

jsat index .                                  # incremental, parallel (4-8× faster)
jsat index src/payments/ --force             # full re-index
jsat index . --branch feature/new-api --languages python,go
jsat index . --watch                          # continuous re-index on save

How incremental mode works:

On the first run JSAT writes index-manifest.json in the data directory (see Data Storage) containing an mtime + sha256 entry for every indexed file. On subsequent runs only files whose content actually changed are re-parsed; everything else is skipped. A 500-file repo with 5 changed files goes from ~3 s to ~100 ms.

Rich metadata extracted (v0.2.0+):

Every Function node now includes parameters, return_type, decorators, docstring, complexity, and loc. Every Class node includes bases, decorators, docstring, and method_count. New edge types INHERITS, IMPLEMENTS, and RAISES are also created.

`jsat shell`¶

Start the JSAT interactive shell.

jsat shell [OPTIONS]

Flag	Default	Description
`--repo`, `-r`	`.`	Repository root
`--verbose`, `-v`	false	Enable DEBUG logging

jsat shell
jsat shell --repo /path/to/project

Inside the shell, type natural language questions or built-in commands:

> what does this project do?
> blast-radius src/payment/refund.py
> security-review
> incident "500 errors since 14:00"
> switch claude
> status
> help

`jsat claude`¶

Open Claude Code with all JSAT MCP tools available.

jsat claude [OPTIONS]

Flag	Default	Description
`--repo`, `-r`	`.`	Repository root
`--verbose`, `-v`	false	Enable DEBUG logging

jsat claude
jsat claude --repo /path/to/project

Requires Claude Code CLI to be installed. JSAT must be connected first (jsat connect claude).

`jsat gpt`¶

Open a GPT-4o session with JSAT tools.

jsat gpt [OPTIONS]

Flag	Default	Description
`--repo`, `-r`	`.`	Repository root
`--verbose`, `-v`	false	Enable DEBUG logging

export OPENAI_API_KEY=sk-...
jsat gpt

`jsat ollama`¶

Open JSAT's Ollama shell, or launch a coding tool with an Ollama local/cloud model.

jsat ollama [OPTIONS]

Flag	Default	Description
`--repo`, `-r`	`.`	Repository root
`--model`, `-m`	selector	Ollama model name; cloud-suffixed names select cloud inference
`--tool`, `-t`	—	Coding tool to launch, such as `claude`, `opencode`, or `codex`
`--config`	false	Configure the coding tool without launching it
`--yes`, `-y`	false	Skip Ollama selectors; requires `--model`
`--verbose`, `-v`	false	Enable DEBUG logging

jsat ollama
jsat ollama --model qwen2.5:0.5b
jsat ollama --tool opencode                 # auto-connect JSAT, then choose a model
jsat ollama --tool opencode --model qwen2.5:0.5b # explicit local model
jsat ollama --tool opencode --model <model>-cloud   # Ollama Cloud

OpenCode does not need to be installed separately; ollama launch opencode handles it. Run jsat connect opencode explicitly only when you want to configure MCP without launching. jsat connect ollama tool=opencode is an equivalent Ollama-oriented spelling.

Managed AI-client lifecycle¶

jsat start [TOOL] [--via auto|native|ollama] [--model MODEL] [--repo PATH]
jsat stop [TOOL] [--force]
jsat restart [TOOL] [--via auto|native|ollama] [--model MODEL] [--repo PATH]
jsat resume [TOOL] [--session ID] [--via auto|native|ollama]
jsat ps

TOOL accepts claude, codex, opencode, or all; the default is all. --via auto reuses the previous route when available, otherwise prefers a PATH-visible native binary and falls back to Ollama. An OpenCode binary found only in Ollama's fallback installation directory therefore uses Ollama automatically. Supplying --model with the auto route also selects Ollama. Restart preserves each client's previous route, model, and repository unless overridden.

Multi-client start/restart/resume opens one terminal window per interactive client. Single-client operations stay in the current terminal. stop affects only processes whose PID and process-start identity were recorded by JSAT. jsat ps shows these records. State defaults to ~/.jsat/runtime/ and can be isolated with JSAT_RUNTIME_DIR.

jsat resume is for Claude/Codex/OpenCode conversation sessions. Use jsat session resume for an interrupted JSAT skill workflow.

`jsat doctor`¶

Run a system health check. Shows system, services, AI providers, and index status.

jsat doctor [OPTIONS]

Flag	Default	Description
`--refresh`	false	Re-detect system (ignore cached profile)
`--json`	false	Output raw JSON

jsat doctor
jsat doctor --refresh
jsat doctor --json | jq '.ai'

`jsat connect github`¶

Wire GitHub's MCP server into the same config JSAT uses, so an AI can pair codebase knowledge with issue history.

jsat connect github [TOOL] [OPTIONS]

Argument / Flag	Default	Description
`TOOL`	`claude`	`claude`, `cursor`, `codex`, `opencode`, `bob`, `windsurf`, `gemini`
`--scope` / `-s`	`project`	`project` (this repo) or `global` (all projects)
`--global` / `-g`	false	Shorthand for `--scope global`
`--remote`	false	Use GitHub's hosted endpoint instead of the local Docker image
`--token-env`	`GITHUB_PERSONAL_ACCESS_TOKEN`	Name of the env var holding your PAT

jsat connect github
jsat connect github cursor --global
jsat connect github --remote
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...     # `repo` scope; `read:org` for orgs

The token value is never written to disk. Only the variable name goes into the config as ${GITHUB_PERSONAL_ACCESS_TOKEN}; the MCP client expands it at run time. Adding GitHub preserves an existing jsat entry — the two sit side by side.

The workflow the guidance instructs the AI to follow: locate the failure with the graph → search GitHub for a known issue → read the PR that caused a regression → file a report built from a privacy-filtered jsat improve bundle. Raw tracebacks are never pasted into GitHub, and creating an issue, comment, or PR asks you first.

`jsat session`¶

Inspect and resume the sessions written by long-running skills (magic, crack, sprint, prompt).

jsat session list  [--skill <name>] [--status <s>] [--limit N]
jsat session show  [<fragment>]
jsat session resume [<fragment>]
jsat session rm    <fragment>
jsat session prune [--keep N] [--all]

Subcommand	Purpose
`list`	Every session, newest first, with `done/total` progress and status
`show`	Steps and findings for one session (default: newest)
`resume`	Where it stopped, the findings carried forward, and how to continue
`rm`	Delete one session file
`prune`	Delete old sessions; unfinished ones are kept unless `--all`

jsat session list --status in_progress
jsat session resume
jsat session prune --keep 20

Sessions live in ~/.jsat/sessions/ (override with JSAT_SESSIONS_DIR) as plain markdown with YAML frontmatter, a ## Steps checklist, and a ## Findings section. The format is implemented in jsat/_sessions.py, so skills, --continue, and this CLI all agree on it — and because the files stay human-editable, ticking a checkbox by hand is honoured on the next read.

`jsat note`¶

Capture and recall project knowledge. Notes are knowledge entries with category: note, so they are searchable next to ADRs and runbooks and visible to every AI tool through the MCP knowledge tools — there is no separate notes store.

jsat note add    <text> [--category <cat>]
jsat note list   [--category <cat>] [--limit N]
jsat note search <query> [--limit N]

Flag	Default	Description
`--category` / `-c`	`note`	`note`, `adr`, `runbook`, `pattern`, `decision`. `list -c all` shows everything
`--limit` / `-n`	20 / 10	Rows to display

jsat note add "retry logic uses tenacity per ADR-007"
jsat note add -c adr "all payment mutations require idempotency keys"
jsat note list -c all
jsat note search retry

`jsat plan`¶

Approve and run stored MCP plans. Any AI tool can propose a call with _mode=plan — nothing executes, JSAT persists the proposal as a markdown session file in JSAT_SESSIONS_DIR — and this command lets a human inspect, approve, run, or discard it. See jsat__execute_plan for the MCP-side approval.

jsat plan list                  [--status <proposed|in_progress|completed|abandoned|rejected>]
jsat plan show  <plan-id>
jsat plan approve <plan-id>
jsat plan run   <plan-id>       [--repo/-r PATH]
jsat plan discard <plan-id>

jsat plan list
jsat plan show  plan-demo-backfill
jsat plan approve plan-demo-backfill
jsat plan run   plan-demo-backfill     # dispatches through the real MCP layer

Plan IDs are slug-ified descriptions (plan-demo-backfill). Running a completed plan is refused (already completed). Distinct from the pre-implementation /jsat plan AI skill, which reviews a task before any code is written.

`jsat improve`¶

Diagnose problems JSAT hit in itself and draft a patch to JSAT's own source.

JSAT passively records friction it encounters internally — crashes, capability gaps, unhelpful error messages, and tools that exceed their time budget. This command turns the most frequent recorded issue into a diagnosis plus a candidate patch.

jsat improve [OPTIONS]

Flag	Default	Description
`--list` / `-l`	false	Show what has been recorded; analyse nothing
`--id <fp8>`	—	Work on one specific issue (ids come from `--list`)
`--report`	false	Open a pre-filled GitHub issue in the browser
`--dry-run`	false	With `--report`, print the URL instead of opening a browser
`--submit <bundle>`	—	Maintainer only — apply a bundle in a JSAT checkout

jsat improve --list
jsat improve
jsat improve --id 85be55de --report

Output is an inert bundle at ~/.jsat/improve/bundles/<id>/:

File	Contents
`manifest.json`	version, install kind, cluster, pre-patch file hashes, patch status
`analysis.md`	root cause and reasoning
`patch.diff`	candidate unified diff
`issue.md`	ready-to-post issue body

patch_status is one of validated (the diff applies cleanly), did_not_apply, no_patch (model returned no diff), ai_error, or no_ai (no provider reachable — a diagnosis-only bundle is still written and the command exits 0).

Privacy. Only JSAT-internal data is recorded: JSAT's own stack frames as paths relative to the package, exception type names, tool names, versions, and config keys. Anything referencing your code, paths, identifiers or queries is dropped, not redacted. Capture writes to a local file only; nothing leaves the machine unless you run --report, which opens a pre-filled issue for you to read and submit yourself. JSAT never modifies its own installed files — a patch is validated against a throwaway copy and stays data until a human merges it.

Disable with JSAT_NO_IMPROVE=1, privacy.no_telemetry: true, or improve.enabled: false. Capture is automatically off in CI.

`jsat version`¶

Print the installed JSAT version.

jsat version
# jsat 0.4.12

`jsat blast-radius`¶

Trace the downstream impact of a change. Offline — no AI provider needed.

jsat blast-radius process_payment                       # a symbol
jsat blast-radius --diff origin/main...HEAD             # a git range
jsat blast-radius --diff /tmp/change.patch              # a diff file
jsat blast-radius --diff origin/main...HEAD --output blast-radius.md
jsat blast-radius src/payments/service.py --max-depth 3 --json

Flag	Default	Description
`target` (positional)	—	Symbol, file, or node id. Omit when using `--diff`.
`--diff`, `-d`	—	A git range (`origin/main...HEAD`), a path to a unified diff file, or diff text
`--max-depth`	`5`	Traversal depth
`--output`, `-o`	—	Write a Markdown report (table + Mermaid graph)
`--fail-on-breaking`	off	Exit non-zero when any breaking impact is found
`--json`	off	Emit JSON to stdout

A --diff value that is neither a file nor diff text is resolved with git diff. An unresolvable range exits 2 rather than silently reporting no impact.

`jsat contract-check`¶

Compare API contracts (OpenAPI / AsyncAPI) between two git refs. Offline.

jsat contract-check --base origin/main
jsat contract-check --base v1 --head v2
jsat contract-check --base v1 --head v2 --json
jsat contract-check --base origin/main --no-fail-on-breaking   # report only

Flag	Default	Description
`--base`, `-b`	`origin/main`	Base ref to compare from
`--head`	`HEAD`	Head ref to compare to
`--fail-on-breaking` / `--no-fail-on-breaking`	on	Exit non-zero when a breaking change is detected
`--json`	off	Emit JSON to stdout

Detects removed endpoints and paths, newly required fields (including multi-line YAML required: lists), and reports a compatibility score of 100·e^(-0.15 · breaking_count).

`jsat security-review`¶

OWASP scan, secret detection, and a live dependency CVE lookup against osv.dev. Offline apart from the CVE lookup.

jsat security-review .
jsat security-review . --sarif security.sarif            # for CI upload
jsat security-review src/config.py --severity low        # a single file
jsat security-review . --no-deps --fail-on-critical

Flag	Default	Description
`path` (positional)	`.`	File or directory to scan
`--severity`, `-s`	`medium`	Minimum severity: `critical`/`high`/`medium`/`low`
`--sarif`	—	Write a SARIF 2.1.0 report (GitHub code scanning, GitLab SAST)
`--no-deps`	off	Skip the dependency CVE lookup
`--fail-on-critical`	off	Exit non-zero if any critical finding is present
`--json`	off	Emit JSON to stdout

Three independent sources are merged under one severity threshold: Semgrep (p/owasp-top-ten, p/secrets — a no-op if Semgrep is absent), regex plus Shannon-entropy secret detection, and CVE lookups for parsed requirements. Secret values are never printed or stored.

Passing a single file scans that file — a suffix outside the scannable set is logged rather than reported clean.

`jsat crack`¶

Run a multi-agent war room on a complex engineering decision. Six agents run in sequence — each receives all prior agents' findings as context.

Agents: architect → security → implementer → tester → skeptic → moderator

jsat crack "redesign the payment retry system"
jsat crack --phases 4 "add idempotency to the charge endpoint"
jsat crack --single "should we use Redis or Postgres for sessions?"

Option	Description
`--phases N`	Number of phases (2–6, default 6 — one agent per phase)
`--single`	Run all 6 agents at once (may timeout on complex tasks)
`--continue`	Resume the most recent `in_progress` crack session from `~/.jsat/sessions/`

Session file written to ~/.jsat/sessions/crack-<slug>-<ts>.md; actions file auto-executed after synthesis.

`jsat short`¶

Get the shortest possible correct answer (≤3 sentences, or one sentence with --one-line).

jsat short "what does process_refund do?"
jsat short --one-line "what's the auth pattern used here?"

`jsat prompt`¶

Classify, optimize, execute, and verify a codebase question through 6 phases: Discuss → Plan → Execute → Verify → Synthesize.

jsat prompt "what calls process_refund?"
jsat prompt --rewrite "fix the logger in PaymentService.charge"
jsat prompt --type structural "trace the checkout call chain"
jsat prompt --optimize-only "why is checkout slow?"
jsat prompt --single "what does the payment service do?"

Option	Description
`--rewrite` / `--agent`	Phase 1: optimize with 1 LLM rewrite agent
`--agents`	Phase 1: optimize with 3 parallel LLM agents
`--type <type>`	Override query type classification (structural/lookup/security/incident/coverage/general)
`--service <name>`	Scope all query phases to one service
`--optimize-only`	Stop after Phase 1; show optimized prompt only
`--single`	Original one-shot flow (no phasing)
`--phases N`	Override phase count (2–6, default 6)
`--continue`	Resume the most recent `in_progress` prompt session from `~/.jsat/sessions/`

Session file written to ~/.jsat/sessions/prompt-<slug>-<ts>.md; actions file auto-executed after Phase 6.

Note: The five sections below (magic, plan, decide, sprint, cohesion) are AI skills, not real jsat CLI subcommands — they do not appear in jsat --help and cannot be run from a plain shell. They are invoked as /jsat <name> ... from inside a connected AI tool (Claude Code, Codex, etc.) once jsat connect claude (or the equivalent connect command) has installed the /jsat dispatcher. See /jsat dispatcher below for how the dispatcher routes these.

`/jsat magic` (AI skill, not a `jsat` CLI subcommand — run inside a connected AI tool such as Claude Code or Codex)¶

AI-orchestrated skill composer. Analyzes any task, selects the right skills from all 50, and runs them in the optimal order.

/jsat magic add retry logic to the payment service
/jsat magic --depth deep redesign the authentication flow
/jsat magic --preview investigate the checkout 500 errors   # plan only
/jsat magic --service PaymentService what are the test gaps?

Option	Description
`--depth quick\\|standard\\|deep`	Cap skills at 4/8/15 (default: standard)
`--budget N`	Explicit cap on skill invocations
`--service <name>`	Scope all skills to one service
`--preview`	Compose and show the plan; do not run
`--continue`	Resume the most recent `in_progress` magic session from `~/.jsat/sessions/`

Session file written to ~/.jsat/sessions/magic-<slug>-<ts>.md; actions file auto-executed after synthesis.

`/jsat plan` (AI skill, not a `jsat` CLI subcommand)¶

Pre-implementation planning gate. Six forcing questions + scope, architecture, and security review.

/jsat plan add idempotency keys to the payment mutation
/jsat plan --scope refactor the retry logic
/jsat plan --security add a new admin endpoint

`/jsat decide` (AI skill, not a `jsat` CLI subcommand)¶

Architectural decision journal. Log decisions; retrieve by file, topic, or blast-radius context.

/jsat decide log --impact h Chose PostgreSQL for ACID compliance
/jsat decide context src/payments/service.py
/jsat decide search caching strategy
/jsat decide list adr

`/jsat sprint` (AI skill, not a `jsat` CLI subcommand)¶

Seven-stage delivery workflow: Think → Plan → Build → Review → Test → Ship → Reflect.

/jsat sprint add rate limiting to the checkout API
/jsat sprint --stage 4 add rate limiting    # resume from Review
/jsat sprint --dry redesign auth flow
/jsat sprint --continue                     # resume most recent interrupted sprint

Option	Description
`--stage N`	Start from stage N (1–7), skipping earlier stages
`--dry`	Show the sprint plan without running any tools
`--continue`	Resume the most recent `in_progress` sprint session from `~/.jsat/sessions/`

Session file written to ~/.jsat/sessions/sprint-<slug>-<ts>.md; actions file auto-executed after Stage 7.

`/jsat cohesion` (AI skill, not a `jsat` CLI subcommand)¶

Code health analysis — flags oversized files, high-complexity functions, and mixed responsibilities.

/jsat cohesion src/
/jsat cohesion --threshold 600 --service PaymentService
/jsat cohesion --functions jsat/cli.py

2. AI Commands (`jsat ai`)¶

`jsat ai status`¶

Show which AI providers are available and which is currently configured.

jsat ai status

Output columns: Provider, Status, Free, Notes/Models.

`jsat ai use`¶

Configure JSAT to use a specific AI provider.

jsat ai use PROVIDER [OPTIONS]

Argument / Flag	Description
`PROVIDER`	`ollama`, `anthropic`, `openai`, `gemini`, `deepseek`, `lmstudio`, `claude_cli`, `opencode`, `bob_cli`, `codex-cli`
`--model`, `-m`	Explicit model; native CLI providers use their own selection when omitted
`--config`, `-c`	Config file to write (default: `.jsat/config.yaml`, or `~/.jsat/config.yaml` with `--global`)
`--global`, `-g`	Write to `~/.jsat/config.yaml` — applies to all projects on this machine

# Per-repo (writes .jsat/config.yaml)
jsat ai models ollama
jsat ai use ollama --model qwen2.5:0.5b
jsat ai use anthropic --model <model>
jsat ai use anthropic --model claude-haiku-4-5-20251001
jsat ai use openai --model gpt-4o-mini
jsat ai use claude_cli
jsat ai use codex-cli
jsat ai use opencode
jsat ai use lmstudio --model <model>

# Global (writes ~/.jsat/config.yaml)
jsat ai use claude_cli --global
jsat ai use anthropic --global

Runs a connectivity test after writing and reports whether the AI is reachable.

`jsat ai test`¶

Send a test prompt to the configured AI and print the response.

jsat ai test [PROMPT]

Argument	Default	Description
`PROMPT`	`"Say hello in one sentence."`	Prompt to send

jsat ai test
jsat ai test "what is 2 + 2?"

`jsat ai models`¶

List available models for the configured provider.

For Ollama: queries http://localhost:11434/api/tags
For LM Studio: queries http://localhost:1234/v1/models
For cloud providers: shows the currently configured model (no remote list)

jsat ai models

3. Connect Commands (`jsat connect`)¶

JSAT works as an MCP server with any AI tool that supports the Model Context Protocol. One command wires it in — all 69 JSAT MCP tools are immediately available to the AI.

`jsat connect claude`¶

Wire JSAT into Claude Code as an MCP server and install the /jsat dispatcher (47 subcommands) and /jsat-help.

jsat connect claude [OPTIONS]

Flag	Default	Description
`--scope`, `-s`	`project`	`project` → `.claude/settings.json` \| `global` → `~/.claude/settings.json`
`--global`, `-g`	false	Shorthand for `--scope global` — one-time setup for all Claude projects
`--repo`, `-r`	`.`	Repo path passed to the MCP server
`--install-skills/--no-skills`	`--install-skills`	Install `/jsat-*` slash commands
`--show`	false	Print the written config

jsat connect claude                         # project scope
jsat connect claude --global                # global — all Claude Code sessions (recommended)
jsat connect claude --scope global          # same as --global
jsat connect claude --no-skills             # MCP only, no slash commands
jsat connect claude --show                  # print config after writing

Restart Claude Code after running.

`/jsat` dispatcher¶

jsat connect claude installs two commands:

/jsat <subcommand> — single dispatcher routing to all 47 skills
/jsat-help [command] — standalone help command; no args lists all 47 commands with one-liners; /jsat-help <command> shows full flags and examples

/jsat-help               # list all 47 subcommands with descriptions
/jsat-help magic         # full flags and examples for /jsat magic
/jsat query <question>   # answer codebase questions (6-phase Discuss→Verify)
/jsat crack <task>       # multi-agent war room (artifact carry-forward)
/jsat aw <task>          # workflow advisor (classify + run optimal sequence)
/jsat lazy <task>        # reuse-first: check what exists before writing new code
/jsat smart <question>   # terse mode: compressed answers, no filler
/jsat security [path]    # OWASP scan + CVE check + secret detection
/jsat blast-radius <target>  # blast radius analysis
/jsat review <diff>      # multi-model code review

Skill files are bundled in the JSAT package at jsat/commands/jsat-*.md and read directly by _write_jsat_dispatcher() when jsat connect claude runs. Updates to skill files are picked up automatically on next jsat connect claude.

MCP server authentication¶

The MCP server defaults to open access with a startup warning when no auth env vars are set. Auth is only enforced when explicitly configured.

Env var	Effect
(none)	Open access — tools work, warning logged at startup
`JSAT_MCP_ALLOW_INSECURE=1`	Open access, warning silenced — written automatically by `jsat connect claude`
`JSAT_MCP_TOKEN=<secret>`	Legacy single-token auth — all callers must pass this token
`JSAT_MCP_TOKEN_ROLES=<json>`	RBAC map `{"token": "role"}` — roles: `admin`, `developer`, `viewer`

jsat connect claude automatically sets JSAT_MCP_ALLOW_INSECURE=1 in the MCP server environment so local dev works without additional config. To enforce auth, add JSAT_MCP_TOKEN or JSAT_MCP_TOKEN_ROLES to your shell environment before starting Claude Code.

`jsat connect codex`¶

Wire JSAT into the OpenAI Codex CLI as an MCP server and Codex skill.

jsat connect codex [OPTIONS]

Flag	Default	Description
`--scope`, `-s`	`global`	Deprecated compatibility option; Codex uses `~/.codex/config.toml`
`--global`, `-g`	false	Deprecated compatibility option; Codex config is always global
`--repo`, `-r`	`.`	Compatibility option; repo is resolved from Codex's working directory at runtime
`--no-instructions`	false	Skip installing `~/.codex/skills/jsat/SKILL.md`

jsat connect codex                          # global MCP config + $jsat skill
jsat codex --repo /path/to/repo              # launch Codex in a specific repo
jsat codex resume <session-id>               # resume an existing Codex session
$jsat magic investigate the checkout flow     # inside Codex

Writes global Codex files: - ~/.codex/config.toml — one [mcp_servers.jsat] table - ~/.codex/skills/jsat/SKILL.md — one Codex skill dispatcher

No .codex/, AGENTS.md, or .agents/skills files are generated in the target repo. In Codex, use $jsat magic TASK, $jsat query QUESTION, or ask naturally. The dispatcher also treats @jsat magic TASK as the same JSAT request when Codex routes it to the skill. Direct MCP tools such as jsat__query, jsat__blast_radius, jsat__security_review, jsat__get_test_gaps, and jsat__submit_for_review remain available.

jsat codex forwards extra arguments to the real Codex CLI after auto-connecting JSAT, so Codex commands such as resume <session-id> keep working.

`jsat connect opencode`¶

Wire JSAT into OpenCode's MCP config and install the /jsat and /jsat-help commands. By default this writes to the current repo (.opencode/opencode.json + .opencode/commands/ and an AGENTS.md guidance block), mirroring jsat connect claude; pass --global for the machine-wide ~/.config/opencode/ config. A directly installed OpenCode and ollama launch opencode use the same files.

jsat connect opencode
jsat connect opencode --global
jsat connect opencode --repo /path/to/project --no-commands --no-agents-md

Flag	Default	Description
`--global`, `-g`	false	Write `~/.config/opencode/opencode.json` instead of `<repo>/.opencode/`
`--repo`, `-r`	`.`	Project to pin the MCP command to (project scope only)
`--install-commands`	true	Install the `/jsat` and `/jsat-help` slash commands
`--agents-md`	true	Write the JSAT guidance block into the repo's `AGENTS.md` (project only)
`--show`	false	Print the generated config

`jsat connect ollama`¶

Configure JSAT in clients that Ollama can launch. With no selector, this configures all clients JSAT currently supports: Claude, Codex, and OpenCode.

jsat connect ollama
jsat connect ollama opencode
jsat connect ollama tool=opencode
jsat connect ollama --tool opencode

Flag	Default	Description
`--tool`, `-t`	`all`	Configure one supported client
`--show`	false	Print generated config where supported

Ollama is the launcher and model selector, not the MCP client. These commands write each client's normal config rather than a separate Ollama MCP file.

`jsat connect cursor`¶

Wire JSAT into Cursor as an MCP server.

jsat connect cursor [OPTIONS]

Flag	Default	Description
`--repo`, `-r`	`.`	Repo path for the MCP server

jsat connect cursor

Writes to ~/.cursor/mcp.json. Restart Cursor after running.

Note: Cursor reads .cursorrules from the project root as agent instructions.

`jsat connect windsurf`¶

Wire JSAT into Windsurf (Codeium) as an MCP server and write .windsurfrules.

jsat connect windsurf [OPTIONS]

Flag	Default	Description
`--repo`, `-r`	`.`	Repo path for the MCP server
`--no-instructions`	false	MCP config only — skip .windsurfrules

jsat connect windsurf

Writes two files: - ~/.codeium/windsurf/mcp_config.json — MCP server registration - .windsurfrules — JSAT tool guidance (Windsurf reads from project root automatically)

Restart Windsurf after running.

`jsat connect continue`¶

Wire JSAT into Continue.dev as an MCP server and add 10 /jsat-* custom commands.

jsat connect continue [OPTIONS]

Flag	Default	Description
`--repo`, `-r`	`.`	Repo path for the MCP server
`--no-instructions`	false	MCP config only — skip custom commands

jsat connect continue

Writes to ~/.continue/config.json: - mcpServers array entry — MCP server registration - customCommands entries — 10 /jsat-* slash commands: /jsat-query, /jsat-blast-radius, /jsat-security, /jsat-review, /jsat-test-gaps, /jsat-knowledge, /jsat-incident, /jsat-prompt-rewrite, /jsat-tokens, /jsat-ithinking

Reload Continue (Cmd/Ctrl+Shift+P → "Continue: Reload") to activate.

`jsat connect zed`¶

Wire JSAT into Zed editor as a context server and write .zed/JSAT.md.

jsat connect zed [OPTIONS]

Flag	Default	Description
`--repo`, `-r`	`.`	Repo path for the MCP server
`--no-instructions`	false	Context server only — skip .zed/JSAT.md

jsat connect zed

Writes two files: - ~/.config/zed/settings.json — context_servers registration - .zed/JSAT.md — JSAT tool guidance (project context for Zed)

Restart Zed after running.

`jsat connect gemini`¶

Wire JSAT into the Google Gemini CLI as an MCP server and write GEMINI.md.

jsat connect gemini [OPTIONS]

Flag	Default	Description
`--repo`, `-r`	`.`	Repo path for the MCP server
`--no-instructions`	false	MCP config only — skip GEMINI.md

jsat connect gemini

Writes two files: - ~/.gemini/settings.json — MCP server registration - GEMINI.md — JSAT tool guidance (Gemini CLI reads from project root automatically)

Restart Gemini CLI after running.

`jsat connect bob`¶

Wire JSAT into Bob Shell (@ibm/bob-shell) as an MCP server, write BOB.md guidance, and install /jsat-* slash commands.

jsat connect bob [OPTIONS]

Flag	Default	Description
`--scope`, `-s`	`project`	`project` → `.bob/settings.json` \| `global` → `~/.bob/settings.json`
`--global`, `-g`	false	Shorthand for `--scope global` — all Bob sessions
`--repo`, `-r`	`.`	Repo path for the MCP server
`--no-instructions`	false	Skip writing BOB.md
`--install-commands/--no-commands`	`--install-commands`	Install `/jsat-*` slash commands

jsat connect bob                            # project scope
jsat connect bob --global                   # global — all Bob sessions (recommended)

Writes: - .bob/settings.json (or ~/.bob/settings.json) — MCP server registration - .bob/commands/jsat-*.md (or ~/.bob/commands/) — 47 slash commands - BOB.md — JSAT tool guidance (Bob Shell reads from project root automatically)

`jsat connect list`¶

Show all AI tools that have JSAT wired as an MCP server.

jsat connect list

Checks known config locations:

Tool	Config file
Claude Code (project)	`.claude/settings.json`
Claude Code (global)	`~/.claude/settings.json`
Codex	`~/.codex/config.toml`
Cursor	`~/.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Continue	`~/.continue/config.json`
Zed	`~/.config/zed/settings.json`
Gemini CLI	`~/.gemini/settings.json`

4. Disconnect Commands (`jsat disconnect`)¶

Remove JSAT from one or all AI tools.

jsat disconnect TOOL [OPTIONS]

Argument	Default	Description
`TOOL`	`claude`	`claude` \| `codex` \| `cursor` \| `windsurf` \| `continue` \| `zed` \| `gemini` \| `all`
`--scope`, `-s`	`project`	`project`, `global`, or `all`. Claude uses project/global; Codex removes its global MCP entry and skill by default and only touches project legacy files with `--scope all`.
`--keep-skills`	false	Keep `/jsat-*` skill files when disconnecting from Claude Code

jsat disconnect claude                       # Claude Code project scope
jsat disconnect claude --scope global        # Claude Code global
jsat disconnect claude --scope all           # Claude Code everywhere
jsat disconnect claude --keep-skills         # remove MCP entry, keep slash commands
jsat disconnect codex                        # Codex global MCP entry + $jsat skill
jsat disconnect cursor                       # Cursor
jsat disconnect windsurf                     # Windsurf
jsat disconnect continue                     # Continue.dev
jsat disconnect zed                          # Zed
jsat disconnect gemini                       # Gemini CLI
jsat disconnect all                          # every tool at once

Restart the relevant AI tool after disconnecting.

5. Init Command¶

`jsat init`¶

Generate a starter JSAT config for a given profile.

jsat init [OPTIONS]

Flag	Default	Description
`--profile`, `-p`	`solo`	`solo`, `team`, `ci`, or `raspberry-pi`
`--output`, `-o`	`.jsat/config.yaml`	Output path (ignored when `--global` is set)
`--global`, `-g`	false	Write to `~/.jsat/config.yaml` — applies to all projects on this machine

# Per-repo config
jsat init --profile solo
jsat init --profile team
jsat init --profile ci
jsat init --profile raspberry-pi

# Global config — one-time setup, applies to all projects
jsat init --global --profile solo

--global writes ~/.jsat/config.yaml. Any repo that does not have its own .jsat/config.yaml automatically uses the global config.

6. CI Setup Command¶

`jsat ci-setup`¶

Write a CI workflow file for JSAT. By default targets GitHub Actions; use --provider gitlab for GitLab CI.

jsat ci-setup [OPTIONS]

Flag	Default	Description
`--provider`, `-p`	`github`	CI provider: `github` or `gitlab`
`--output`, `-o`	provider default	Output path for the workflow file

jsat ci-setup                        # writes .github/workflows/jsat.yml
jsat ci-setup --provider gitlab      # writes .gitlab-ci.yml

The generated workflow runs jsat index and jsat doctor --json on every push and pull request. It uses the ci profile automatically (no AI calls, JSON logs, memory cache).

7. Prompt Optimizer (`jsat prompt`)¶

Optimize any query through a 7-stage pipeline before sending it to the AI. Auto-optimization runs on every shell message by default.

`jsat prompt <query>`¶

Print the optimized prompt without sending it to the AI. Use this to inspect what would be sent.

jsat prompt "improve the retry logic"
jsat prompt "explain the auth flow"

`jsat prompt --send`¶

Optimize the query and send it to the configured AI provider.

jsat prompt --send "improve the retry logic"
jsat prompt --send "write a test for refund()"

`jsat prompt --diff`¶

Show a side-by-side comparison of the raw input and the full optimized prompt (with injected context, constraints, few-shot examples, and model formatting).

jsat prompt --diff "improve the retry logic"

Flags¶

Flag	Values	Description
`--send`	—	Optimize and send to the AI
`--diff`	—	Show raw input vs optimized prompt side by side
`--format`, `-f`	`code`, `plan`, `json`, `prose`	Override output format for this prompt
`--ai`	`claude`, `gpt`, `ollama`	Override AI provider for this prompt
`--cot`	—	Append chain-of-thought instructions to the prompt
`--verbose`	—	Print a stage-by-stage breakdown of the pipeline
`--dry-run`	—	Inspect the full optimized prompt without sending or printing the AI response
`--no-context`	—	Skip graph context injection (stages 2)
`--no-examples`	—	Skip few-shot example injection (stage 4)

jsat prompt --send --format code --ai claude "write a test for refund()"
jsat prompt --send --cot --verbose "debug why checkout is returning 500"
jsat prompt --dry-run --no-context "what does the payment service do?"

Shell commands (`opt`)¶

Inside the JSAT shell, use the opt command to control optimization:

opt on        # enable auto-optimization for all messages (default)
opt off       # disable for the current session
opt show      # show raw input vs full optimized prompt for the last message
opt history   # browse past optimization diffs

8. JSAT Crack (`jsat crack`)¶

Run a multi-agent war room on a complex engineering decision.

jsat crack TASK [OPTIONS]

Argument / Flag	Default	Description
`TASK`	(required)	The complex engineering question to discuss
`--roles`, `-r`	all 6	Comma-separated subset: `architect,security,implementer,tester,skeptic`
`--rounds`, `-n`	`3`	Number of discussion rounds
`--file`, `-f`	auto	Write output to file (default: `.jsat/crack/<slug>.md`)
`--repo`	`.`	Repository root

jsat crack "redesign payment retry system"
jsat crack --roles architect,security "migrate users table to UUID"
jsat crack --rounds 2 "sync vs async for webhook processing"
jsat crack --file design.md "how should we handle idempotency keys"

Agents (run in parallel, respond to each other across rounds): - 🏛 architect — system design, patterns, scalability - 🔒 security — threat model, auth, idempotency - ⚙️ implementer — current code analysis, effort estimate - 🧪 tester — edge cases, coverage gaps, testability - 😈 skeptic — challenges every proposal - 🎯 moderator — synthesises consensus and action plan (always last)

Output is saved to .jsat/crack/<slug>.md.

Works without AI configured (returns structural offline placeholders).

8b. JSAT Short (`jsat short`)¶

Get the shortest possible correct answer to any question.

jsat short QUESTION [OPTIONS]

Argument / Flag	Default	Description
`QUESTION`	(required)	Question to ask
`--words`, `-w`	`50`	Maximum word count
`--one-line`, `-1`	false	Exactly one sentence
`--repo`, `-r`	`.`	Repository root

jsat short "what does process_refund do"
jsat short --one-line "is PaymentService.process async"
jsat short --words 10 "explain the retry logic"

In the JSAT shell: short <question>

10. Token Optimizer (`jsat tokens`)¶

Count tokens, check model budget, and compress text for AI prompts. All offline — zero LLM calls.

jsat tokens [TEXT] [OPTIONS]

Argument / Flag	Default	Description
`TEXT`	—	Inline text to analyze
`--file`, `-f`	—	Read from file instead
`--model`, `-m`	—	Model for the budget check, e.g. `claude-opus-5`, `gpt-4o`, or an Ollama tag
`--compress`, `-c`	false	Apply compression strategies and print savings
`--strip-comments`	false	Also remove code comment lines
`--no-dedup`	false	Skip semantic deduplication
`--target`, `-t`	—	Explicit token ceiling for compression
`--verbose`, `-v`	false	Show per-section token breakdown

# Count tokens
jsat tokens "explain the payment service"
jsat tokens --file README.md

# Budget check
jsat tokens --file context.py --model gpt-4o
jsat tokens --file context.py --model claude-cli

# Compress
jsat tokens --file context.py --compress
jsat tokens --file context.py --compress --target 4000 --strip-comments

# Pipe stdin
cat big_file.py | jsat tokens --model claude-cli --compress

8b. Maintenance Commands¶

`jsat clean`¶

Remove cached data from .jsat/ to free disk space or force a fresh start.

jsat clean [OPTIONS]

Flag	Description
`--cache`	Delete `.jsat/cache/`
`--graph`	Delete `.jsat/graph/` (destroys the index)
`--vectors`	Delete `.jsat/vectors/`
`--history`	Delete `.jsat/prompt-history.jsonl`
`--all`	Delete all of the above

jsat clean --cache          # free cache only
jsat clean --all            # full reset

`jsat update`¶

Self-upgrade JSAT via pip.

jsat update [--pre]

Flag	Description
`--pre`	Include pre-release versions

`jsat refresh`¶

Check for a newer JSAT version and re-sync the bundled skills into every connected AI tool. Reads jsat/commands/jsat-*.md, works out what each tool should have, diffs it against what's on disk, and updates only what changed — adding new skills, updating modified ones, removing vanished ones. Tools that are not connected are skipped; the installed package itself is never modified.

jsat refresh [OPTIONS]

Flag	Default	Description
`--repo PATH`	`.`	Repo path for project-scope skill targets
`--ai TOOL`	all	Only `claude`, `codex`, `opencode`, `bob` or `continue`
`--check-only`	false	Report what would change, write nothing
`--update`	false	Also `pip install --upgrade jsat` when newer
`--pre`	false	With `--update`: allow pre-release versions
`--no-skills`	false	Version check only; skip the skill sync
`--no-version`	false	Skill sync only; skip the PyPI version check

jsat refresh
jsat refresh --check-only
jsat refresh --ai codex
jsat refresh --update

`jsat knowledge-ingest`¶

Bulk-ingest markdown files (CLAUDE.md, ADRs, runbooks) into the knowledge base.

jsat knowledge-ingest PATH [OPTIONS]

Argument / Flag	Default	Description
`PATH`	(required)	Directory to scan
`--pattern`	`*/.md`	Glob pattern for files to ingest
`--category`	auto	Override category (adr, runbook, readme)
`--dry-run`	false	Print what would be ingested, don't write

jsat knowledge-ingest docs/             # ingest all .md files
jsat knowledge-ingest . --pattern "**/*.md" --dry-run

11. Export and Import¶

`jsat export`¶

Export the current index to a portable zip archive.

jsat export OUTPUT [OPTIONS]

Argument / Flag	Default	Description
`OUTPUT`	(required)	Output path, e.g. `backup.jsat.zip`
`--compress`, `-z`	`6`	Compression level 0-9 (0 = no compression, 9 = max)

jsat export backup.jsat.zip
jsat export backup.jsat.zip --compress 9

`jsat import`¶

Restore an index from an exported archive.

jsat import ARCHIVE [OPTIONS]

Argument / Flag	Default	Description
`ARCHIVE`	(required)	Path to `.jsat.zip` archive
`--migrate`	false	Apply schema migrations if version differs

jsat import backup.jsat.zip

12. Remove Command¶

`jsat remove`¶

Remove all JSAT artifacts from the current repository. Interactive confirmation by default.

jsat remove [OPTIONS]

Flag	Default	Description
`--yes`, `-y`	false	Skip confirmation prompt
`--keep-config`	false	Keep `.jsat/config.yaml` (preserve settings)

Removes:

.jsat/graph/ — codebase graph database
.jsat/vectors/ — embedding vectors
.jsat/cache/ — semantic cache
.jsat/system-profile.json
.jsat/config.yaml (unless --keep-config)
.claude/commands/jsat-*.md — skill files
mcpServers.jsat entry in .claude/settings.json

Does not touch your source code, git history, or other Claude configuration.

jsat remove
jsat remove --yes              # skip confirmation
jsat remove --keep-config      # preserve config.yaml

13. Skills Commands (`jsat skills`)¶

`jsat skills list`¶

List installed JSAT skills (YAML manifests in the skills directory).

jsat skills list

`jsat skills run`¶

Run a named skill.

jsat skills run NAME [OPTIONS]

Argument / Flag	Description
`NAME`	Skill name
`--args`, `-a`	`key=val` pairs (repeatable)

jsat skills run my-skill
jsat skills run my-skill --args target=src/api.py --args depth=3

14. MCP Server (Internal)¶

`jsat mcp-server`¶

Start the JSAT MCP server on stdin/stdout. This is invoked automatically by Claude Code and Cursor when JSAT is connected. You do not normally run this directly.

jsat mcp-server [OPTIONS]

Flag	Default	Description
`--repo`, `-r`	`.`	Repository root to serve
`--verbose`, `-v`	false	Enable debug logging

If you need to test the MCP server manually:

jsat mcp-server --repo /path/to/project --verbose

The server speaks JSON-RPC 2.0 over stdin/stdout. It starts immediately and loads JSAT lazily to avoid startup timeout errors in Claude Code.

Universal Flags (Claude Code slash commands)¶

Two flags work on every /jsat command — strip them before routing and pass to every tool call:

Flag	Behavior	Passes to tool
`timeout=<N>`	Soft budget N s; hard kill at 5×N s	`_budget=N`
`dashboard=true`	Open `localhost:7432/jsat/dashboard/<command>` — one persistent tab per command, collapsible tree of all tool calls. Tab stays open until session done. Browse all sessions at `localhost:7432/jsat/dashboard`.	`_dashboard=True` + `_dashboard_session=<command>`

/jsat blast-radius timeout=120 src/payment/
/jsat crack dashboard=true redesign the auth flow
# → opens localhost:7432/jsat/dashboard/crack

/jsat magic timeout=180 dashboard=true investigate the auth flow
# → opens localhost:7432/jsat/dashboard/magic

Environment Variables¶

Variable	Used by
`JSAT_CONFIG`	Override config file path
`JSAT_DASHBOARD_PORT`	Override live dashboard port (default `7432`)
`JSAT_RUNTIME_DIR`	Override managed AI-client lifecycle records
`ANTHROPIC_API_KEY`	Anthropic API provider
`OPENAI_API_KEY`	OpenAI provider
`GEMINI_API_KEY` or `GOOGLE_API_KEY`	Gemini provider
`JSAT_AI_PROVIDER`	Override AI provider for this process (`codex_cli`, `claude_cli`, etc.)
`NEO4J_PASSWORD`	Neo4j graph backend
`QDRANT_API_KEY`	Qdrant vector store
`JSAT_MCP_TOKEN`	MCP server auth token (if `mcp.auth: true`)
`CI`	If `true`/`1`/`yes`, forces CI profile (no embeddings, memory cache)

CLI Reference¶

1. Core Commands¶

jsat index¶

jsat shell¶

jsat claude¶

jsat gpt¶

jsat ollama¶

Managed AI-client lifecycle¶

jsat doctor¶

jsat connect github¶

jsat session¶

jsat note¶

jsat plan¶

jsat improve¶

jsat version¶

jsat blast-radius¶

jsat contract-check¶

jsat security-review¶

jsat crack¶

jsat short¶

jsat prompt¶

/jsat magic (AI skill, not a jsat CLI subcommand — run inside a connected AI tool such as Claude Code or Codex)¶

/jsat plan (AI skill, not a jsat CLI subcommand)¶

/jsat decide (AI skill, not a jsat CLI subcommand)¶

/jsat sprint (AI skill, not a jsat CLI subcommand)¶

/jsat cohesion (AI skill, not a jsat CLI subcommand)¶

2. AI Commands (jsat ai)¶

jsat ai status¶

jsat ai use¶

jsat ai test¶

jsat ai models¶

3. Connect Commands (jsat connect)¶

jsat connect claude¶

/jsat dispatcher¶

MCP server authentication¶

jsat connect codex¶

jsat connect opencode¶

jsat connect ollama¶

jsat connect cursor¶

jsat connect windsurf¶

jsat connect continue¶

jsat connect zed¶

jsat connect gemini¶

jsat connect bob¶

jsat connect list¶

4. Disconnect Commands (jsat disconnect)¶