JSAT — JaySoft AI Tools

Codebase intelligence for AI sessions — index once, query forever, works with any AI.

🧠 What is JSAT?

Every AI session starts with the same problem: you spend the first ten minutes re-explaining your architecture, re-pasting function signatures, and re-describing how services talk to each other. JSAT solves this by building a persistent graph of your codebase once — functions, classes, files, services, API endpoints, database tables, Kafka topics, and every relationship between them — and making that context instantly available to any AI you use.

JSAT works as a CLI, a Python SDK, and an MCP server that plugs into Claude Code, Codex, Cursor, Bob Shell, Gemini CLI, and other MCP-capable tools. If a supported local CLI is installed, JSAT can use it as the AI provider with no API key required. For hosted APIs and local servers — Anthropic API, OpenAI, Gemini, Ollama, LM Studio — one command switches the provider.

Long-running tools stream live progress notifications to Claude Code — and with dashboard=true on any command, a real-time browser dashboard opens automatically showing every event as it happens.

🌟 Key Features

⚡ Quick Start

pip install jsat

# Index your project
cd your-project/
jsat index .

# Open your AI tool with JSAT pre-loaded (auto-connects on first use)
jsat claude      # Claude Code
jsat codex       # OpenAI Codex CLI
jsat codex resume <session-id>
jsat opencode    # OpenCode (project scope)
jsat cursor      # Cursor IDE
jsat windsurf    # Windsurf
jsat gemini      # Google Gemini CLI
jsat zed         # Zed editor
jsat bob         # Bob Shell

# War room discussion (new!)
jsat crack "redesign payment retry system"

# Shortest possible answer (new!)
jsat short "what does process_refund do"

Inside any connected tool you can use JSAT commands:

Claude Code slash commands:

/jsat query what does the payment service do?
/jsat blast-radius src/payment/refund.py
/jsat security
/jsat incident "500 errors spiking on checkout"
/jsat prompt-rewrite fix logger in ValidateVPAHandler.post

Continue.dev custom commands (same commands, /jsat-* prefix)

Codex skill commands:

$jsat magic add retry logic to the payment service
$jsat query what does the payment service do?
@jsat magic investigate the checkout flow

$jsat is the preferred Codex skill invocation. JSAT's Codex dispatcher also treats @jsat as the same request when Codex routes it to the skill.

All tools have all JSAT MCP tools the AI can call automatically.

📦 Installation

JSAT ships as a minimal core with optional extras. Install only what you need.

pip install jsat                   # core only
pip install 'jsat[local]'          # + Ollama
pip install 'jsat[standard]'       # + security analysis, OpenAPI validation
pip install 'jsat[team]'           # + Neo4j, Qdrant, Redis
pip install 'jsat[anthropic]'      # + Claude API SDK
pip install 'jsat[openai]'         # + OpenAI SDK
pip install 'jsat[all]'            # everything

🤖 AI Providers

JSAT auto-detects available providers at startup and picks the best one in priority order:

1. Claude Code CLI — detected via which claude; no API key, no extra SDK
2. Bob Shell CLI — detected via which bob; no API key, IBM AI assistant with multiple modes
3. OpenAI Codex CLI — detected via which codex; no API key after Codex sign-in
4. Anthropic API — if ANTHROPIC_API_KEY is set and jsat[anthropic] is installed
5. OpenAI — if OPENAI_API_KEY is set and jsat[openai] is installed
6. Ollama — if ollama serve is running at localhost:11434 and at least one model is pulled (a running daemon with zero models cannot complete a request — check ollama list first)
7. LM Studio — if an OpenAI-compatible server is running at localhost:1234
8. No AI — tools that don't need AI (indexing, blast radius, export) still work

Check what's available

jsat ai status        # shows all providers, which is active, and switch commands

Switch providers

jsat ai models ollama                     # discover registered local/cloud models
jsat ai use ollama --model qwen2.5:0.5b    # exact tag; see `ollama list`
jsat ai use anthropic --model <model>     # needs ANTHROPIC_API_KEY
jsat ai use openai --model gpt-4o-mini    # needs OPENAI_API_KEY
jsat ai use claude_cli                    # Claude chooses its configured/default model
jsat ai use opencode                      # OpenCode CLI (uses its selected provider/model)
jsat ai use codex-cli                     # Codex chooses its configured/default model
jsat ai use deepseek --model deepseek-chat  # needs DEEPSEEK_API_KEY
jsat ai use lmstudio --model <model>      # OpenAI-compat server at localhost:1234
jsat ai test                              # verify the configured provider works

# Apply globally (all projects on this machine):
jsat ai use claude_cli --global

Switch inside the JSAT shell

switch claude    → Claude Code CLI (no key) or Claude API
switch bob       → Bob Shell (no key)
switch codex     → OpenAI Codex CLI
switch gpt <model>       → OpenAI API with an explicit model
switch ollama <model>    → Ollama with a registered local/cloud model
switch haiku <model>     → Anthropic API; alias never pins a model version
switch phi <model>       → Ollama; choose an installed Phi-family model
switch lmstudio <model>  → LM Studio with its loaded model ID
switch deepseek <model>  → DeepSeek API (needs DEEPSEEK_API_KEY)

🔌 AI Tool Integration

JSAT works as an MCP server with any AI tool that supports the Model Context Protocol. One command wires it in — the tool picks up all JSAT MCP tools automatically.

Choose your execution path

The coding client and the model provider are separate choices. Use the guide for the process you actually want to run; this prevents native Codex/Claude from being confused with a client that Ollama launched.

Local Ollama models require one ollama pull MODEL. Ollama Cloud models require ollama signin and no pull. A model selected by ollama launch applies to that launched client; it does not silently become the provider in .jsat/config.yaml.

Open the tabbed integration chooser.

⏱ Universal Flags

Two flags work on every /jsat command — strip them from ARGS before routing, pass as tool args:

# Set a custom soft time budget (notification-only; hard kill at 5×N)
/jsat blast-radius timeout=60 src/payment/
  → jsat__blast_radius(target='src/payment/', _budget=60)

# Open a live browser dashboard for this call
/jsat crack dashboard=true redesign the auth flow
  → jsat__crack(task='redesign the auth flow', _dashboard=True)

# Combine both
/jsat magic timeout=180 dashboard=true --service payments investigate the auth flow

✏️ Universal Input Correction & Learning Module

Every /jsat <command> invocation runs two extra passes by default, before and after the subcommand itself:

Before routing — free-form ARGS are cleaned up (typos, run-on phrasing, ambiguous pronouns tightened) via jsat__prompt_rewrite before being handed to the subcommand. Literal payloads are never touched: file paths, diffs/patches, code blocks, git refs/SHAs, and URLs are passed through verbatim even when they sit next to prose that gets corrected. If the rewrite meaningfully changes ARGS, the AI reports what changed with a one-line 📝 Interpreted as: <rewritten> before proceeding, so a bad guess is visible and correctable rather than silently substituted. Add raw=true to any command to skip this step entirely and route ARGS exactly as typed (e.g. /jsat query raw=true find PaymnetService).

After completion — a short pass checks whether the command surfaced anything worth remembering beyond this conversation. Most invocations produce nothing durable and this runs silently with no output. When something concrete is learned, it's classified and saved via jsat__knowledge_add:

• Project-specific facts (a gotcha, a non-obvious dependency, a false-positive pattern to exclude next time) are saved to this project's knowledge base (category="project-learning") — searchable later with /jsat knowledge.
• JSAT-specific facts (a tool misbehaving, a missing capability, a stale parameter) are saved to JSAT's own improvement backlog (category="jsat-improvement"), which /jsat improve reads from later — this is feedback about JSAT itself, not the user's repo.

📊 Live Dashboard

Add dashboard=true to any /jsat command and a real-time browser dashboard opens automatically. Each /jsat command gets one persistent tab — all tool calls in that session stream into the same collapsible tree, not separate tabs.

/jsat magic dashboard=true investigate the checkout flow
/jsat crack dashboard=true redesign the payment retry system
/jsat blast-radius dashboard=true timeout=60 src/payment/

URL: http://localhost:7432/jsat/dashboard/<command> — e.g., /jsat crack ... opens localhost:7432/jsat/dashboard/crack.

What the tree shows:

• Session header with live elapsed timer and status badge (● RUNNING → ✓ DONE)
• Each tool call as a collapsible section with its name and elapsed time
• Sub-calls nested under their parent (e.g., crack phases under a parent crack call)
• Every checkpoint, result, and event streamed in real-time, color-coded by type:
  • 🟡 Amber — checkpoints (substep progress)
  • 🟢 Green — results (completed)
  • 🔵 Blue — agent full responses (crack war room agents)
  • 🔴 Red — errors
  • 🟠 Orange — over-budget warnings
• Copy logs button to capture the full session

Session lifecycle:

• Tab opens on the first tool call; subsequent calls in the same /jsat session stream into the same tab.
• Tab stays open until the entire /jsat command finishes. An idle watcher fires session_done automatically after 30 s with no active calls.
• After session done the tree dims (✓ DONE) — the tab stays open indefinitely for reading.

For multi-tool sessions (magic, crack, sprint) the skill files automatically pass _dashboard_session=<command> in every tool call so all calls share one tab — no manual action needed.

The dashboard runs on localhost:7432 (override with JSAT_DASHBOARD_PORT), served by a pure stdlib SSE server — no extra dependencies.

Connect

# Recommended: one-time global setup (works in every project)
jsat connect claude --global               # Claude Code — all sessions
jsat connect codex                        # OpenAI Codex CLI — global MCP + $jsat skill
jsat connect opencode                     # OpenCode — MCP + /jsat commands (project scope)
jsat connect opencode --global            # OpenCode — all projects (recommended one-time)
jsat connect ollama                       # Claude + Codex + OpenCode Ollama integrations
jsat connect ollama tool=opencode         # only OpenCode (also accepts --tool opencode)
jsat connect ollama opencode --model <model>  # + remember this model for `jsat ollama opencode`
jsat connect bob --global                 # Bob Shell — all sessions

# If Ollama manages OpenCode, connect once and use Ollama's normal menu:
ollama                                    # OpenCode → sign in → choose model

# Managed lifecycle (defaults to all: Claude + Codex + OpenCode)
jsat start                                # one terminal per interactive client
jsat ps                                   # show JSAT-managed clients
jsat restart                              # restart all three clients
jsat stop                                 # stop all running managed clients
jsat resume                               # resume all three clients
jsat restart opencode                     # target one client

# Per-project (this repo only)
jsat connect claude                        # Claude Code
jsat connect bob                           # Bob Shell (+ /jsat-* slash commands)
jsat connect cursor                        # Cursor
jsat connect windsurf                      # Windsurf (Codeium)
jsat connect continue                      # Continue.dev
jsat connect zed                           # Zed editor
jsat connect gemini                        # Google Gemini CLI

jsat connect github                        # GitHub MCP server, beside JSAT
jsat connect list                          # show every active connection

Restart the AI tool after connecting. JSAT's MCP tools are immediately available.

Claude reaches for JSAT on its own. jsat connect claude also writes a marked block into CLAUDE.md, which Claude Code loads every session. Slash commands only fire when you type one; the CLAUDE.md block is what makes Claude proactively run jsat__blast_radius before an edit, jsat__get_test_gaps before writing tests, and say in one line what each tool actually found. Skip it with --no-claude-md; jsat disconnect claude removes the block and leaves the rest of your CLAUDE.md untouched.

Files written per tool

Most connect commands write both an MCP config and a guidance file so the AI knows what JSAT tools exist and when to use them — without being asked. Codex stays global-only: JSAT writes one global MCP entry plus one global Codex skill dispatcher, without generating project files.

Pass --global (claude/bob) or check the tool's docs for global scope on others.

Pass --no-instructions to skip writing guidance files on integrations that support them.

/jsat dispatcher

jsat connect claude installs a single /jsat command rather than 47 individual /jsat-* commands. All skills are accessible as subcommands:

/jsat help               # list all 47 subcommands
/jsat query <question>   # answer codebase questions (Discuss→Verify pipeline)
/jsat crack <task>       # multi-agent war room with artifact carry-forward
/jsat aw <task>          # workflow advisor
/jsat lazy <task>        # reuse-first planning
/jsat smart <question>   # terse compressed answers

Skill files are bundled inside the JSAT package at jsat/commands/ and sourced directly when jsat connect claude runs.

Disconnect

jsat disconnect claude                     # Claude Code project scope
jsat disconnect claude --scope all         # Claude Code everywhere
jsat disconnect codex                      # Codex
jsat disconnect cursor                     # Cursor
jsat disconnect windsurf                   # Windsurf
jsat disconnect continue                   # Continue
jsat disconnect zed                        # Zed
jsat disconnect gemini                     # Gemini CLI
jsat disconnect all                        # every tool at once

Claude Code — slash commands (47 subcommands + /jsat-help)

jsat connect claude installs two slash commands:

• /jsat <subcommand> — 47 subcommands organized by category (see table below)
• /jsat-help [command] — no args lists all commands; /jsat-help magic shows full flags and examples for that command

Graph exploration

Impact & safety

Code quality

Git workflow

Knowledge & investigation

Prompt & token tools

IThinking

Analysis & planning

Help

Open Claude with JSAT context pre-loaded

jsat claude

⚔️ JSAT Crack — Multi-Agent War Room

Run a complex engineering decision past a panel of six specialist AI agents that argue, challenge, and respond to each other — like a real architecture meeting.

jsat crack "redesign payment retry system"
jsat crack --roles architect,security "migrate users table to UUID"
jsat crack --rounds 2 --file design.md "sync vs async webhooks"

Agents (all run in parallel per round, then respond to each other):

Phased mode (v0.4.0+): By default, each agent runs in its own phase (N=6) so you see results after every agent instead of waiting for all 6. Each agent receives all prior findings as context — the architect's conclusions inform the security analysis, and the skeptic specifically challenges the architect's and implementer's proposals.

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?"

Output: A Markdown document saved to .jsat/crack/<slug>.md with each round's discussion and a final synthesis:

✅ Agreed:        Use exponential backoff with tenacity
⚠️ Disputed:      Redis vs in-process lock for idempotency
❓ Open questions: What's the SLA for retry exhaustion?
🎯 Action:        1. Extract retry logic, 2. Add idempotency key, 3. Write tests

In Claude Code: /jsat crack redesign the payment retry system

In the JSAT shell: crack should we use async or sync for webhook processing

MCP tool: jsat__crack

Live progress — while the war room runs you see real-time updates in Claude Code:

⚡ Loading codebase context…
⚡ Round 1/3: Opening statements…
⚡ Round 1/3: Moderator synthesising…
⚡ Round 2/3: Cross-examination…
⚡ Round 3/3: Consensus…
⚡ Writing discussion document…
[result]

💬 JSAT Short — Minimum-Word Answers

Get the shortest possible correct answer to any question.

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

In Claude Code: /jsat short what does process_refund do

In the JSAT shell: short is the checkout flow async

🔧 Prompt Optimizer

JSAT optimizes every query through a two-phase pipeline before sending to the AI.

Phase 1 — Offline pipeline (always runs, zero LLM calls)

jsat prompt "improve the retry logic"              # inspect optimized prompt
jsat prompt --send "improve the retry logic"       # optimize + send
jsat prompt --diff "improve the retry logic"       # see raw vs optimized side by side
jsat prompt --send --format code --ai claude "write a test for refund()"

Phase 2 — LLM rewriting (optional, activated with a flag)

After the offline pipeline structures the prompt, 1–3 specialist LLM agents rewrite the task description from different angles, then the best result is selected by a coverage + specificity scorer.

# 1 agent — fastest, rewrites for clarity and precision
jsat prompt --rewrite "fix logger in this branch"

# 3 agents in parallel — picks the best rewrite
jsat prompt --agents "fix logger in this branch"

# Combine with --send to optimize + rewrite + send in one step
jsat prompt --agents --send "fix logger in ValidateVPAHandler.post"

The 3 LLM agents:

Agents run in parallel. Winner is chosen by: coverage × 0.45 + specificity × 0.40 + efficiency × 0.15.

Discuss → Verify pipeline (v0.4.0+): Before optimizing, the skill classifies the query type and selects the right primary tool — structural questions use jsat__trace_call_chain, lookup questions use jsat__get_function, security questions use jsat__security_review, etc. After executing, Phase 5 spot-checks concrete claims from the answers against the graph, marking each as ✅ verified or ⚠️ unverified before synthesis.

Example output with --agents --verbose:

┌─────────────────────┬──────────────────────────────┐
│ Task type           │ debug                        │
│ Context nodes       │ 3                            │
│ Tokens before       │ 6                            │
│ Tokens after        │ 847                          │
│ Rewrite agents run  │ 3                            │
│ Winner              │ context_expand               │
│ Rewrite time        │ 1843ms                       │
└─────────────────────┴──────────────────────────────┘

✦ 6→847 tokens | Task: debug | 3 agents → context_expand won

In the shell — every message is auto-optimized through Phase 1:

jsat [Claude Code (CLI)]> improve the retry logic

✦ Optimized refactor | 6→847 tokens (35% saved) | 3 ctx nodes | opt show to see diff

Claude: Here's the improved retry using tenacity...

Shell commands:

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

MCP tools:

• jsat__prompt_optimize — offline pipeline only
• jsat__prompt_rewrite — offline + 1 LLM rewrite agent
• jsat__prompt_multi_agent — offline + up to 3 parallel LLM agents

Claude Code slash command:

/jsat prompt-rewrite fix the logger missing extra= dict in ValidateVPAHandler.post

Disconnect or remove

jsat disconnect claude --scope all            # Claude Code everywhere
jsat disconnect all                           # every connected tool at once
jsat remove                                   # remove all JSAT artifacts from this repo

🧩 JSAT Smart — Terse Mode

Get compressed, fragment-based answers with filler stripped. Preserves code, function names, file paths, and data byte-for-byte.

Three compression levels:

/jsat smart what does the payment service do?
/jsat smart --ultra what does process_refund return?
/jsat smart --lite explain the checkout flow

Use as a fast fallback when /jsat query times out on large contexts.

♻️ JSAT Lazy — Reuse-First Planning

Before writing new code, runs a 5-rung reuse ladder against the indexed codebase graph. Stops at the first match.

# Check before building new retry logic
/jsat lazy add exponential backoff to the payment service

# Scan a diff for code that reimplements existing things
/jsat lazy --audit src/payments/retry.py

# Check if a proposed implementation duplicates existing code
/jsat lazy --review "def process_refund(order_id, amount)..."

🗺️ JSAT Aw — Workflow Advisor

Classifies your task type and runs the optimal JSAT tool sequence end-to-end — no more guessing which tool to use or in what order.

# Classify automatically and run the full workflow
/jsat aw add idempotency keys to the payment mutation endpoint

# Skip classification, force a specific workflow type
/jsat aw --type security src/auth/

# Show the recommended workflow without running it
/jsat aw --dry investigate the checkout 500 errors from this morning

✨ JSAT Magic — AI-Orchestrated Skill Composer

The only JSAT skill with no fixed template. Given any task, it:

1. Analyzes the task to understand what information is needed
2. Composes a minimal effective skill sequence from all 40 skills, organized in layers
3. Executes each skill with task-specific parameters, adapting based on findings
4. Converges when the task is answerable — skips remaining skills once sufficient data exists

/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, no execution
/jsat magic --service PaymentService what are the test gaps?

Depth flags: --depth quick (4 skills), --depth standard (8, default), --depth deep (15). --preview shows the composed plan without running anything.

📋 JSAT Plan — Pre-Implementation Planning Gate

Runs before writing any code. Surfaces assumptions, scope risks, and architectural concerns by answering six forcing questions, then reviewing from three perspectives.

Six Forcing Questions:

1. What is the exact problem?
2. Who experiences it and how often?
3. What is the cost of NOT solving it?
4. What already exists in the codebase that partially handles this?
5. What is the minimum change that solves it?
6. What is the hardest part — and what assumption am I making about it?

Three review perspectives: Scope (what to build and why), Architecture (how to build it), Security (what can go wrong).

Output: a one-page planning brief with recommended decision, architecture approach, top risk, and first concrete step.

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

📓 JSAT Decide — Architectural Decision Journal

Log architectural decisions into the knowledge base and retrieve them by file, topic, or blast-radius context — so past decisions inform future changes.

/jsat decide log --impact h Chose PostgreSQL over MongoDB for ACID compliance on payment records
/jsat decide log Switched caching from Redis to in-memory — cost $500/month, latency acceptable
/jsat decide context src/payments/service.py     # decisions relevant to this file
/jsat decide search caching strategy
/jsat decide list adr                            # list all ADR-category decisions

Subcommands: log [--impact h|m|l], list [<category>], search <query>, context <file_or_symbol>

🚀 JSAT Sprint — Seven-Stage Delivery Workflow

Structured end-to-end delivery. Each stage runs focused JSAT tools and passes its findings forward to the next.

/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"       # show plan without running

🏥 JSAT Cohesion — Code Health Analysis

Flags files and functions that have grown beyond healthy boundaries, then cross-references with blast-radius to prioritize the most urgent refactoring targets.

• Files > 800 lines (adjustable with --threshold N)
• Functions with cyclomatic complexity > 10
• Classes with > 15 methods

Output: RED / YELLOW / GREEN priority report with specific extraction suggestions.

/jsat cohesion src/
/jsat cohesion --threshold 600 --service PaymentService
/jsat cohesion --functions jsat/cli.py    # function-level analysis only

🐙 GitHub MCP — turn errors into resolved issues

JSAT knows what broke in your codebase. GitHub knows whether anyone has hit it before. jsat connect github wires GitHub's MCP server in beside JSAT so an AI has both.

jsat connect github                  # Docker image, Claude Code, this repo
jsat connect github cursor --global  # Cursor, all projects
jsat connect github --remote         # GitHub's hosted endpoint (no Docker)

export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...   # `repo` scope; `read:org` to search orgs

Your token never touches disk. Only the environment variable name is written into the config (${GITHUB_PERSONAL_ACCESS_TOKEN}); the MCP client expands it at run time.

With both connected, the guidance JSAT writes tells the AI to work in this order:

Raw tracebacks are never pasted into GitHub — a jsat improve bundle is privacy-filtered, a traceback is not. Reading is unprompted; creating an issue, comment, or PR asks you first.

📝 Notes & Knowledge

Capture something worth remembering without leaving the terminal. Notes are stored as knowledge entries (category: note), so they are searchable alongside your ADRs and runbooks — and visible to every connected AI tool through the MCP knowledge tools.

jsat note add "retry logic uses tenacity per ADR-007"
jsat note add -c adr "all payment mutations require idempotency keys"
jsat note list                    # notes only
jsat note list -c all             # every knowledge entry
jsat note search retry            # semantic search across notes + ADRs + runbooks

There is no second store to keep in sync: jsat note is a thin CLI over the same KnowledgeTool that backs jsat__knowledge_query, /jsat knowledge, and /jsat decide.

🔁 JSAT Improve — Self-Improvement

JSAT watches for friction in itself — crashes, capability gaps, unhelpful errors, tools that blow their time budget — and can turn what it finds into a fix proposal for JSAT.

jsat improve --list      # what JSAT has recorded about itself
jsat improve             # diagnose the top issue, draft a patch → bundle on disk
jsat improve --report    # open a pre-filled GitHub issue for you to review and submit

When one issue recurs, JSAT tells you:

💡 JSAT hit IndexNotFound 3x and may be able to fix itself — run: jsat improve

jsat improve reads the recorded issue, pulls the relevant JSAT source, asks your configured AI provider to diagnose it and produce a unified diff, validates that diff in a throwaway sandbox, and writes a bundle to ~/.jsat/improve/bundles/:

What is collected — and what is not

Anything that cannot be proven JSAT-internal is dropped, not redacted — a record that trips the filter is discarded whole, and jsat improve --list tells you how many were dropped. Capture writes to a local file only; nothing leaves your machine unless you run --report, which opens a pre-filled issue in your browser for you to read and submit yourself.

JSAT never modifies its own installed files. A generated patch is inert data — it is validated against a temporary copy and only becomes code after a human reviews it in a pull request.

Turning it off

export JSAT_NO_IMPROVE=1              # this shell

improve:
  enabled: false                      # or nudge: false to keep capture, drop the hint
privacy:
  no_telemetry: true                  # also disables capture

Capture is automatically disabled in CI.

In Claude Code: /jsat improve · MCP tool: jsat__improve_status (read-only)

💾 Session Files & Auto-Execute

Every major skill (magic, crack, sprint, prompt) writes two files automatically:

Session file — resume interrupted runs

~/.jsat/sessions/<skill>-<slug>-<YYYYMMDD-HHMM>.md

Tracks which steps completed. Inspect and resume sessions from the shell:

jsat session list                 # every session, newest first, with progress
jsat session show                 # steps and findings of the newest session
jsat session resume               # where it stopped + how to continue
jsat session rm <fragment>        # delete one
jsat session prune --keep 20      # tidy up (unfinished ones are kept)

The format is implemented in jsat/_sessions.py, so skills, --continue, and the CLI all read and write the same thing. Files stay plain markdown — tick a checkbox in your editor and JSAT honours it. Override the location with JSAT_SESSIONS_DIR.

Inside an AI tool, pass --continue to pick up where a run left off:

/jsat magic --continue        # resume most recent interrupted magic session
/jsat crack --continue        # resume most recent interrupted crack session
/jsat sprint --continue       # resume most recent interrupted sprint
/jsat prompt --continue       # resume most recent interrupted prompt pipeline

The session file uses YAML frontmatter (status: in_progress / completed) and markdown checkboxes (- [ ] / - [x]) so it's human-readable.

Actions file — auto-execute synthesis recommendations

~/.jsat/sessions/<skill>-actions-<slug>-<YYYYMMDD-HHMM>.md

After each skill finishes its analysis and writes its synthesis, it extracts the concrete recommended actions (commands to run, files to edit with line numbers, tests to write, commits to make) and writes them to an actions file. The AI then immediately executes each action in sequence, marking [x] as it goes:

📋 Actions: ~/.jsat/sessions/crack-actions-redesign-payment-20260731-1430.md
  ✅ Fix entropy threshold security.py line 112: done
  ✅ Add .claude to IndexerConfig exclude_patterns: done
  ✅ python -m pytest tests/ -q → 356 passed, 9 skipped: done
✅ All actions complete: ~/.jsat/sessions/crack-actions-redesign-payment-20260731-1430.md

The skill recommends and acts — nothing falls through the cracks.

📖 CLI Reference

Core commands

Configuration

AI provider management

AI tool integrations

Token analysis

Export and import

Skills

Maintenance

🐍 Python SDK

from jsat import JSAT

# Instantiate — auto-detects AI provider, loads config
js = JSAT(repo=".")

# Build the graph — parallel parsing, incremental by default
result = js.index()
print(f"Indexed {result.nodes_indexed} nodes in {result.duration_ms}ms")
print(f"Workers: {result.parallel_workers} | Incremental: {result.incremental}")
print(f"Skipped: {result.files_skipped} unchanged | Resolved: {result.resolved_edges} edges")
if result.complexity_hotspots:
    print("Hotspots:", [(h["name"], h["complexity"]) for h in result.complexity_hotspots])

# Natural language query over the graph
result = js.query("what calls the refund endpoint?")
print(result.answer)

# Trace blast radius of a change
report = js.blast_radius("src/payment/refund.py")
for item in report.impacts:
    print(f"{item.severity:10s}  {item.node_id}")

# Security analysis (requires jsat[standard])
sec = js.security_review(path="src/")
for finding in sec.findings:
    print(f"{finding.severity}: {finding.title} — {finding.file}:{finding.line}")

# Incident investigation
incident = js.investigate_incident("500 errors on checkout", since="24h")
for h in incident.hypotheses:
    print(f"[{h.score:.0%}] {h.title}")

# Export the index for sharing or CI caching
manifest = js.export("snapshot.jsat.zip")
print(f"Exported {manifest.size_mb:.1f} MB")

# Restore from an export
js2 = JSAT.from_import("snapshot.jsat.zip")

# Token analysis (offline, no LLM)
count = js.token_count("explain the payment service")
report = js.token_compress(large_prompt, model="gpt-4o")
print(f"Saved {report.savings_pct:.1f}% via: {report.strategies_applied}")
budget = js.token_budget(my_context, "claude-cli")
print(f"{budget['budget_pct']:.2f}% of context used ({budget['status']})")

# Switch AI provider mid-session
js.switch_ai("ollama", model="qwen2.5:0.5b")
js.switch_ai("anthropic", model="<model>")
js.switch_ai("gpt", model="gpt-4o-mini")

# Health check
health = js.doctor()
print(health["profile"], health["graph"]["backend"])

Tools Overview (26 tools)

Multi-Model Review

Tool 9 dispatches the diff to all configured models in parallel, collects findings, and surfaces only those confirmed by two or more models. Configure the model list and timeout in .jsat/config.yaml:

review:
  models:
    - {provider: claude_cli, model: claude-sonnet-4-6}
    - {provider: ollama, model: qwen2.5:0.5b}
  parallel_timeout_seconds: 90
  min_confidence: medium

• parallel_timeout_seconds — per-review wall-clock deadline; any model that exceeds this is skipped and its absence is logged.
• min_confidence — minimum agreement level to surface a finding: low (any model), medium (2+ models), high (all models).

Graph Schema

JSAT indexes these node types and relationship edges:

Nodes: Function, Class, File, Service, Endpoint, Table, Topic, KnowledgeEntry

Node properties (v0.2.0+):

Edges:

Configuration

Data storage

By default JSAT stores runtime state (graph, cache, vectors, prompt history) in ~/.jsat/<hash12>/ — a global per-repo directory that never appears inside your git working tree. No .gitignore entry needed.

The config file (.jsat/config.yaml) is separate and optional — it holds project-specific settings, not runtime data.

One-time global setup

jsat init --global --profile solo      # write ~/.jsat/config.yaml
jsat ai use claude_cli --global        # set AI provider globally
jsat connect claude --global           # install to ~/.claude/ for all projects

After this, every project on the machine has JSAT available with no per-repo steps.

Per-repo config

jsat init                        # write .jsat/config.yaml (solo profile)
jsat init --profile team         # team profile
jsat init --profile ci           # CI/CD profile

Key settings in .jsat/config.yaml:

graph:
  backend: sqlite          # sqlite (default) | neo4j (team profile)
  path: .jsat/graph/graph.db

embeddings:
  provider: local          # local | openai | none
  model: nomic-embed-code

ai:
  provider: ollama         # also: anthropic, openai, openai_compat, claude_cli, opencode_cli, bob_cli, codex_cli, none
  model: qwen2.5:0.5b
  base_url: null           # for openai_compat (LM Studio, Gemini, etc.)

cache:
  backend: memory          # memory | disk | redis

indexer:
  languages: [python, javascript, go, java, ruby, rust]
  exclude_patterns: ["**/node_modules/**", "**/.git/**", "**/dist/**"]
  max_file_size_kb: 500

ithinking:
  enabled: true
  mode: interactive        # interactive | silent
  gate_level: medium       # low | medium | high

improve:
  enabled: true            # record friction JSAT hits in itself (local file only)
  nudge: true              # hint to run `jsat improve` when an issue recurs
  nudge_threshold: 3       # occurrences before the hint appears
  nudge_cooldown_s: 86400  # min seconds between hints
  github_repo: iamjpsonkar/JaySoft-AI_Tools

Profiles at a glance

Config search order

JSAT finds its config file by checking these locations in order (first found wins):

1. Explicit path passed to JSAT(config=...) or --config flag
2. $JSAT_CONFIG environment variable
3. {repo}/.jsat/config.yaml (repo-local canonical)
4. {repo}/.jsat.yaml (legacy)
5. ./.jsat/config.yaml (CWD)
6. ~/.jsat/config.yaml ← global user config (jsat init --global)
7. ~/.config/jsat/config.yaml
8. /etc/jsat/config.yaml

Supported Languages

All seven are in the default indexer.languages list, so installing the grammar is all it takes — no config change. A language whose optional grammar is absent contributes no nodes for those files rather than failing the index.

Extracted per language: functions (parameters with types and defaults, return type, decorators/annotations, first doc line, cyclomatic complexity), classes (bases, interfaces, method count), and CALLS / IMPORTS / INHERITS / IMPLEMENTS / RAISES edges. Files over indexer.max_file_size_kb (default 500 KB) are skipped.

Contributing

Contributions are welcome. Please open an issue or pull request on GitHub.

Developing JSAT with an AI agent

AGENTS.md is the complete context file: repo map, call flow, an extension cookbook for each surface (CLI / MCP tool / slash command / config / provider), enforced conventions, testing, the environment traps that actually cost time, the privacy and safety invariants, known debt, and a pre-flight checklist. Point any AI agent at it before it touches the code.

Running the tests

./local_test.sh --install    # editable install + dev deps in every venv it finds
./local_test.sh              # lint (identical command to CI) + CI-safe tests
./local_test.sh --doctor     # environment check, no tests
./local_test.sh --all        # everything (needs Neo4j, Qdrant, Redis)
./local_test.sh --both       # run the suite in every venv that has jsat
./local_test.sh --fix        # auto-fix lint

--doctor is worth running first. It catches the two environment problems that waste the most time: a stale non-editable install shadowing your checkout (so your edits do nothing), and typer/click drift between venvs — typer ≥0.27 vendors its own click, so the CLI can behave differently in two environments while the test suite stays green in both.

End-to-end self-test (no mocking)

local_test.sh runs the pytest suite — unit-level, with mocks where the code under test expects them. scripts/jsat-selftest.sh is a different, complementary check: it exercises the currently installed jsat binary as a real black box — real CLI subprocess calls, a real scratch repo indexed for real, the real MCP server driven over real stdio JSON-RPC, and (opt-in) a real headless claude -p agent driving the real /jsat dispatcher. Any external dependency that isn't present (Ollama, Neo4j, Qdrant, a CLI, an API key) is reported as unavailable, never silently skipped and never counted as a failure. Emits a JSON + Markdown report any AI agent can read to triage.

./scripts/jsat-selftest.sh              # full run — free, ~15s
./scripts/jsat-selftest.sh --quick      # skip local_test.sh --all
./scripts/jsat-selftest.sh --live-agent # + a real headless claude agent driving jsat
                                         # claude's real MCP config and a curated set of
                                         # /jsat skills end-to-end — costs real API
                                         # tokens (~$4-5, ~2 min for the full set)

• Repository: github.com/iamjpsonkar/JaySoft-AI_Tools
• Bug reports: open an issue on GitHub
• Author: Jay Prakash Sonkar — iamjpsonkar@gmail.com
• License: MIT

License

MIT License. Copyright (c) Jay Prakash Sonkar.