╭───────────────────────────────────╮
│                                   │
│      ██╗  █████╗  ███╗   ███╗     │
│      ██║ ██╔══██╗ ████╗ ████║     │
│      ██║ ███████║ ██╔████╔██║     │
│  ██  ██║ ██╔══██║ ██║╚██╔╝██║     │
│  ╚████╔╝ ██║  ██║ ██║ ╚═╝ ██║     │
│   ╚═══╝  ╚═╝  ╚═╝ ╚═╝     ╚═╝     │
│                                   │
│   developer-first  AI  CLI        │
│                                   │
╰───────────────────────────────────╯

Why Jam?

Most AI coding tools are built around a single vendor's model, require a browser or IDE plugin, and send your code to a remote server you don't control.

Jam is different by design:

• It runs entirely on your machine by default — your code never leaves your filesystem
• It is not tied to any single model or provider — you choose the engine; Jam is the harness
• It behaves like a proper Unix tool — pipeable, composable, and scriptable
• It treats code modification as a transaction — validate first, preview always, confirm before applying
• It is built to be contributed to — clean TypeScript, well-tested, architecture documented below

Highlights

Design Philosophy

The best developer tools disappear into your workflow. They don't ask you to change how you work — they work the way you already do.

You own the model. Jam's ProviderAdapter is a clean interface — swap the AI engine with a config change, not a rewrite. No vendor lock-in, no model loyalty.

Your code stays private. The default is localhost. Nothing leaves your machine unless you explicitly point Jam at a remote provider. This isn't just a feature — it's the architecture.

Changes are transactions, not actions. jam patch validates with git apply --check before anything is touched, shows a full preview, and waits for explicit confirmation. No "undo" needed — changes never happen without your approval.

Unix composability. jam ask reads stdin, writes stdout, supports --json. It's a pipe stage, not a walled garden.

Security is configuration, not hope. Tool permissions (toolPolicy), allowed operations (toolAllowlist), and log redaction (redactPatterns) are declarative config — committable to .jamrc so your whole team inherits the same guardrails.

Who Is Jam For?

Quick Start

Prerequisites

• Node.js 20+
• Ollama running locally (ollama serve)
• A pulled model: ollama pull llama3.2

Install

# Global install (once published to npm)
npm install -g jam-cli

# Or run from source
git clone https://github.com/sunilp/jam-cli.git
cd jam-cli
npm install
npm run build
npm link          # makes `jam` available globally

Verify

jam doctor        # checks Node version, config, provider connectivity, ripgrep
jam auth login    # validates connection to Ollama

Commands

jam ask

One-shot question. Streams the response to stdout.

jam ask "What is the difference between TCP and UDP?"

# From stdin
echo "Explain recursion in one paragraph" | jam ask

# From a file
jam ask --file prompt.txt

# JSON output (full response + token usage)
jam ask "What is 2+2?" --json

# Override model
jam ask "Hello" --model codellama

# Use a named profile
jam ask "Hello" --profile work

Options:

jam chat

Interactive multi-turn chat REPL (Ink/React TUI).

jam chat                         # new session
jam chat --name "auth refactor"  # named session
jam chat --resume <sessionId>    # resume a previous session

Keyboard shortcuts inside chat:

Sessions are saved automatically to ~/.local/share/jam/sessions/ (macOS: ~/Library/Application Support/jam/sessions/).

jam explain

Read one or more files and ask the model to explain them.

jam explain src/auth/middleware.ts
jam explain src/api/routes.ts src/api/handlers.ts
jam explain src/utils/retry.ts --json

jam search

Search the codebase using ripgrep (falls back to JS if rg is not installed).

jam search "TODO"                          # plain search, prints results
jam search "useEffect" --glob "*.tsx"      # filter by file type
jam search "createServer" --ask            # pipe results to AI for explanation
jam search "error handling" --max-results 50

Options:

jam diff

Run git diff and optionally review it with AI.

jam diff                    # review working tree changes
jam diff --staged           # review staged changes (ready to commit)
jam diff --path src/api/    # limit to a specific directory
jam diff --no-review        # just print the raw diff, no AI
jam diff --staged --json    # JSON output

jam review

Review a branch or pull request with AI.

jam review                        # review current branch against main
jam review --base develop         # diff against a different base branch
jam review --pr 42                # review a specific PR (requires GitHub CLI)
jam review --json                 # JSON output

Options:

jam commit

Generate an AI-written commit message from staged changes and commit.

jam commit                 # generate message, confirm, then commit
jam commit --dry           # generate message only, do not commit
jam commit --yes           # skip confirmation prompt
jam commit --amend         # amend the last commit with a new AI message

Options:

Messages follow the Conventional Commits specification.

jam patch

Ask the AI to generate a unified diff patch, validate it, and optionally apply it.

jam patch "Add input validation to the login function"
jam patch "Fix the off-by-one error in pagination" --file src/api/paginate.ts
jam patch "Add JSDoc comments to all public methods" --dry   # generate only, don't apply
jam patch "Remove unused imports" --yes                      # auto-confirm apply

Flow:

1. Collects context (git status, current diff, specified files)
2. Prompts the model for a unified diff
3. Validates with git apply --check
4. Shows the patch preview
5. Asks for confirmation (unless --yes)
6. Applies with git apply

jam run

Agentic task workflow — the model can call tools in a loop to accomplish a goal.

jam run "Find all TODO comments and summarize them"
jam run "Check git status and explain what's changed"
jam run "Read src/config.ts and identify any security issues"

Available tools (model-callable):

Write tools require confirmation unless toolPolicy is set to allowlist in config.

jam auth

jam auth login    # validate connectivity to the current provider
jam auth logout   # remove stored credentials from keychain

jam config

jam config show            # print merged effective config as JSON
jam config init            # create .jam/config.json in the current directory
jam config init --global   # create ~/.config/jam/config.json

jam context

Manage the JAM.md project context file. This file is auto-read by jam ask and jam chat to give the model awareness of your project's architecture, conventions, and goals.

jam context init           # generate JAM.md at the workspace root
jam context init --force   # overwrite an existing JAM.md
jam context show           # display the current JAM.md contents

jam models list

jam models list            # list models available from the current provider
jam models list --provider ollama --base-url http://localhost:11434

jam history

jam history list           # list all saved chat sessions
jam history show <id>      # show all messages in a session (first 8 chars of ID work)

jam completion install

jam completion install                    # auto-detects shell
jam completion install --shell bash       # bash completion script
jam completion install --shell zsh        # zsh completion script

Follow the printed instructions to add the completion to your shell.

jam doctor

Run system diagnostics:

jam doctor

Checks:

• Node.js version (≥ 20)
• Config file is valid
• Provider connectivity (Ollama reachable)
• ripgrep availability (optional, JS fallback used if absent)
• keytar availability (optional, env vars used if absent)

Configuration

Config File Locations

Jam merges config in priority order (highest wins):

1. CLI flags
2. .jam/config.json  or  .jamrc  (repo-level)
3. ~/.config/jam/config.json     (user-level)
4. Built-in defaults

Config Schema

{
  "defaultProfile": "default",
  "profiles": {
    "default": {
      "provider": "ollama",
      "model": "llama3.2",
      "baseUrl": "http://localhost:11434",
      "temperature": 0.7,
      "maxTokens": 4096,
      "systemPrompt": "You are a helpful coding assistant."
    },
    "fast": {
      "provider": "ollama",
      "model": "qwen2.5-coder:1.5b",
      "baseUrl": "http://localhost:11434"
    }
  },
  "toolPolicy": "ask_every_time",
  "toolAllowlist": [],
  "historyEnabled": true,
  "logLevel": "warn",
  "redactPatterns": ["sk-[a-z0-9]+", "Bearer\\s+\\S+"]
}

Config Fields

Profile Fields

Initialize Config

# Repo-level (committed to version control)
jam config init

# User-level (applies everywhere)
jam config init --global

Using Profiles

# Use a specific profile
jam ask "Hello" --profile fast

# Switch default in config
echo '{"defaultProfile": "fast"}' > .jamrc

Environment Variables

Development

npm run dev -- ask "What is 2+2?"   # run from source with tsx
npm run build                         # compile TypeScript to dist/
npm run typecheck                     # tsc --noEmit
npm run lint                          # ESLint
npm test                              # Vitest unit tests
npm run test:watch                    # watch mode
npm run test:coverage                 # coverage report

Project Structure

src/
├── index.ts        # CLI entry point — command registration (Commander)
├── commands/       # One file per command (ask, chat, run, review, commit, …)
├── providers/      # LLM adapter layer — ProviderAdapter interface + Ollama impl
├── tools/          # Model-callable tools + registry + permission enforcement
├── config/         # Zod schema, cosmiconfig loader, built-in defaults
├── storage/        # Chat session persistence (JSON files)
├── ui/             # Ink/React TUI (chat REPL) + Markdown/streaming renderer
└── utils/          # Shared helpers: streaming, logger, secrets, agent loop, tokens

Adding a New Provider

1. Implement ProviderAdapter from src/providers/base.ts:

import type { ProviderAdapter, ProviderInfo, CompletionRequest, StreamChunk } from './base.js';

export class MyProvider implements ProviderAdapter {
  readonly info: ProviderInfo = { name: 'myprovider', supportsStreaming: true };

  async validateCredentials(): Promise<void> { /* ... */ }
  async listModels(): Promise<string[]> { /* ... */ }
  async *streamCompletion(request: CompletionRequest): AsyncIterable<StreamChunk> { /* ... */ }
}

2. Register in src/providers/factory.ts:

if (provider === 'myprovider') {
  const { MyProvider } = await import('./myprovider.js');
  return new MyProvider({ apiKey: profile.apiKey });
}

3. Use: jam ask "Hello" --provider myprovider

Contributing

Jam is intentionally built to be easy to extend. The architecture is layered, each concern is isolated, and the three main contribution surfaces — providers, tools, and commands — each have a clean interface to implement.

You don't need to understand the whole codebase to contribute. A new provider is one file. A new tool is one file. The patterns are already established and documented.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

Please read our Contributing Guide for details on our code of conduct, development workflow, and pull request process.

Good First Issues

Look for issues labeled good first issue — these are great starting points for new contributors.

What the Codebase Looks Like

• Strict TypeScript throughout — no any, no guessing what a function does
• Tests colocated with source — foo.ts → foo.test.ts, using Vitest
• One file per concern — each command, provider, and tool is self-contained
• Zod schema validation — config is validated at load time, not at runtime when it's too late
• Conventional Commits — the git log tells the story of the project

If you can read TypeScript, you can contribute to Jam.

Community

• Issues — Report bugs or request features
• Discussions — Ask questions, share ideas
• Code of Conduct — Our community standards

Security Policy

We take security seriously. If you discover a vulnerability, please do not open a public issue. Instead, follow the responsible disclosure process in our Security Policy.

Roadmap

• OpenAI provider
• Azure OpenAI provider
• Anthropic Claude provider
• Groq provider
• Plugin system for custom tools
• Token usage tracking and budgets
• Web UI companion

Probable Enhancements

Ideas and directions under consideration. These range from quick wins to deep architectural changes. Contributions, RFCs, and discussion on any of these are welcome.

🧩 Plugin System

The tool registry (ToolRegistry.register()) already accepts any ToolDefinition, but tool discovery is hardcoded. A proper plugin system would allow external tools without modifying source.

• Local plugins — load ToolDefinition modules from .jam/plugins/ or ~/.config/jam/plugins/
• npm plugin packages — jam plugin install @scope/jam-plugin-docker discovers and registers tools at startup
• Plugin manifest — declarative jam-plugin.json with name, version, tool definitions, required permissions
• Lifecycle hooks — onActivate, onDeactivate, beforeToolCall, afterToolCall for plugin-level middleware
• Sandboxed execution — plugins run with restricted filesystem/network access based on declared capabilities

jam plugin install jam-plugin-docker
jam plugin list
jam plugin remove jam-plugin-docker

🎯 Skills

Skills are named, composable mini-agents — each with a focused system prompt, a curated tool subset, and a defined output contract. Think of them as recipes the model can invoke.

• Built-in skills — refactor, test-writer, documenter, security-audit, dependency-update, migration
• Skill registry — each skill declares its name, description, required tools, system prompt template, and output schema
• Composable — skills can call other skills (e.g., refactor invokes test-writer to verify changes)
• User-defined skills — .jam/skills/ directory with YAML/JSON skill definitions
• Skill marketplace — share and import community skills via npm or a registry

# .jam/skills/api-endpoint.yaml
name: api-endpoint
description: Generate a new REST API endpoint with tests
tools: [read_file, write_file, search_text, run_command]
system: |
  You are an API endpoint generator. Given a resource name and
  fields, generate the route handler, validation, tests, and
  OpenAPI schema following the project's existing patterns.
output:
  type: files
  confirm: true

jam skill run refactor --file src/api/auth.ts
jam skill run test-writer --file src/utils/cache.ts
jam skill list

🤖 Sub-Agents & Task Decomposition

The current agent loop (jam run) is a single monolithic ReAct loop. Sub-agents would enable the planner to decompose complex instructions into specialized child tasks.

• Planner agent — breaks a complex instruction into an ordered DAG of sub-tasks
• Specialist delegation — each sub-task dispatched to a purpose-built sub-agent (e.g., "read and understand", "refactor", "write tests", "verify")
• Result aggregation — parent agent collects sub-agent outputs and synthesizes a final result
• Parallel sub-agents — independent sub-tasks execute concurrently (e.g., "write tests" and "update docs" in parallel)
• Scoped context — each sub-agent receives only the context it needs, reducing token waste
• Fail-and-retry isolation — a failed sub-agent can be retried without restarting the entire task

jam run "Refactor the auth module to use JWT, update all tests, and document the changes"
# Planner decomposes into:
#   1. [understand] Read current auth module and tests
#   2. [refactor]   Rewrite auth module with JWT
#   3. [test]       Update tests for new implementation  (parallel with 4)
#   4. [document]   Update docs and JSDoc comments        (parallel with 3)
#   5. [verify]     Run tests and validate the patch

🔌 Connectors

Connectors are adapters for external services — bringing data in and pushing results out. Currently Jam only understands the local filesystem and git.

• GitHub — read/create issues, PRs, review comments; jam review --pr 42 already shells out to gh, a connector would be native
• GitLab / Bitbucket — equivalent PR/MR workflows for non-GitHub teams
• JIRA / Linear / Shortcut — fetch issue context, update status, attach AI-generated summaries
• Slack / Discord — post review summaries, commit digests, or search results to channels
• Database — read schema, run read-only queries, explain query plans
• REST / GraphQL — generic HTTP connector for internal APIs (jam ask "Why is /api/users slow?" --connector api-prod)
• Docker / K8s — read container logs, describe pods, inspect images
• CI/CD — read build logs, trigger pipelines, analyze failures

// .jam/config.json
{
  "connectors": {
    "github": { "token": "env:GITHUB_TOKEN" },
    "jira": { "baseUrl": "https://myorg.atlassian.net", "token": "env:JIRA_TOKEN" },
    "postgres": { "connectionString": "env:DATABASE_URL", "readOnly": true }
  }
}

🧠 MCP (Model Context Protocol) Support

MCP is an open standard for connecting AI models to external tools and data sources. Adding MCP client support would let Jam consume any MCP-compatible server.

• MCP client — Jam discovers and connects to MCP servers declared in config
• Tool bridge — MCP tools appear as native Jam tools in the registry, usable by jam run
• Resource bridge — MCP resources (files, database rows, API responses) injected as context
• Prompt bridge — MCP prompt templates available as Jam skills
• Server mode — expose Jam's own tools (read_file, search_text, git_diff, etc.) as an MCP server for other agents

{
  "mcp": {
    "servers": {
      "filesystem": { "command": "npx @modelcontextprotocol/server-filesystem /path/to/dir" },
      "postgres":   { "command": "npx @modelcontextprotocol/server-postgres", "env": { "DATABASE_URL": "..." } }
    }
  }
}

⚡ Parallel Tool Execution

Currently tools execute sequentially within each agent round. When the model requests multiple independent tool calls (e.g., read three files), they could run concurrently.

• Dependency analysis — detect independent tool calls within a single round
• Concurrent dispatch — Promise.all() for independent read operations
• Write serialization — write tools always execute sequentially and with confirmation
• Progress display — show parallel tool execution status in real time

🔗 Middleware & Hooks

A middleware chain around LLM calls and tool executions, enabling cross-cutting concerns without modifying core logic.

• Pre/post LLM hooks — prompt injection defense, cost tracking, audit logging
• Pre/post tool hooks — rate limiting, output sanitization, metrics
• Error interceptors — custom retry logic, fallback providers, graceful degradation
• Event emitter — structured events (tool:start, tool:end, llm:stream, agent:iteration) for UI decoupling, telemetry, and external integrations

// .jam/middleware/cost-tracker.ts
export default {
  name: 'cost-tracker',
  afterCompletion({ usage, provider, model }) {
    const cost = estimateCost(provider, model, usage);
    appendToLog(`~/.jam/cost.csv`, { timestamp: Date.now(), model, cost });
  }
};

🧭 Embeddings & Vector Search

The current past-session search uses keyword overlap (Jaccard scoring), and the symbol index is regex-based. Optional local embeddings would enable true semantic search.

• Local embedding model — use Ollama's embedding endpoint (nomic-embed-text, mxbai-embed-large) so nothing leaves your machine
• Codebase index — vector index of functions, classes, and doc comments stored at .jam/vectors/
• Semantic code search — jam search "authentication flow" returns semantically relevant code, not just keyword matches
• Session memory — embed past Q&A pairs for cross-session context recall with relevance decay
• RAG pipeline — retrieve relevant code chunks before prompting, reducing token usage and improving accuracy

💰 Cost & Token Tracking

TokenUsage is already captured per request but not aggregated or displayed.

• Session cost estimation — estimate cost based on provider pricing (configurable per-profile)
• Budget limits — maxCostPerSession, maxCostPerDay in config; warn or hard-stop when exceeded
• Usage dashboard — jam usage command showing tokens consumed, cost by model, by command, over time
• Token budget per tool call — prevent runaway context from a single large file read

jam usage                # summary: today, this week, this month
jam usage --detail       # per-session breakdown
jam usage --export csv   # export for expense tracking

📦 Multi-File Transactions

apply_patch and write_file currently operate on single files with no rollback mechanism.

• Transaction block — group multiple file writes into an atomic operation
• Git stash checkpoint — auto-stash before a multi-file edit, restore on failure
• Dry-run preview — show all proposed changes across files before any writes
• Selective accept — accept/reject individual file changes within a transaction

🔍 Provider Capabilities & Feature Negotiation

The ProviderAdapter interface treats all providers equally, but providers differ in capabilities.

• Capability flags — supportsToolCalling, supportsVision, supportsStructuredOutput, supportsEmbeddings on ProviderInfo
• Graceful degradation — if a provider doesn't support tool calling, fall back to prompt-based tool simulation
• Model capability discovery — query the provider for model-specific features at runtime
• Auto-routing — route tasks to the best-fit model/provider (e.g., use a fast model for planning, a capable model for generation)

🧠 Persistent Agent Memory

Working memory is currently session-scoped. Cross-session memory would make Jam smarter over time.

• Workspace knowledge base — facts, patterns, and conventions learned from past sessions, stored per-repo
• Memory decay — older memories lose relevance weight over time unless reinforced
• Explicit memory — jam remember "the auth module uses bcrypt, not argon2" for user-declared facts
• Memory retrieval — automatically surface relevant memories during planning and synthesis
• Forgetting — jam forget to clear or selectively prune memories

🌐 Web UI Companion

A local web interface for sessions that benefit from richer display.

• Diff viewer — syntax-highlighted side-by-side diffs for jam patch and jam review
• Session browser — visual history of past chat sessions with search
• Tool call inspector — expandable timeline of every tool call, its input, output, and duration
• Markdown preview — rendered Markdown responses with code block copy buttons
• Served locally — jam ui starts a local server; no external hosting

🧪 Testing & Verification Skills

First-class support for test generation and verification.

• Test generation — jam test generate src/utils/cache.ts generates tests matching project conventions
• Test-driven patch — jam patch can optionally run tests before and after applying changes
• Coverage-aware context — prioritize uncovered code paths in review and audit workflows
• Regression detection — track which tests fail after a patch and auto-revert if needed

🐚 Shell Integration & Workflow Automation

Deeper shell integration for power users and CI/CD pipelines.

• Git hooks — jam hooks install sets up pre-commit (auto-lint), prepare-commit-msg (AI message), pre-push (review)
• Watch mode — jam watch monitors file changes and provides continuous AI feedback
• Pipeline mode — structured JSON I/O for chaining Jam commands in shell scripts and CI
• Makefile/Taskfile recipes — pre-built task definitions for common workflows

Acknowledgments

Built with these excellent open source projects:

• Commander.js — CLI framework
• Ink — React for CLIs
• Ollama — Local LLM serving
• Zod — Schema validation
• marked — Markdown rendering
• cosmiconfig — Configuration loading

License

MIT License — Copyright (c) 2026-present Sunil Prakash. All rights reserved.

See LICENSE for the full license text.