@sunilp-org/jam-cli 0.1.0 → 0.1.2

package/README.md

@@ -27,7 +27,7 @@
 
 Ask questions • Explain code • Review diffs • Generate patches • Run agentic tasks
 
-*All from your command line, powered by any Ollama-hosted model.*
+*All from your command line, powered by Ollama, OpenAI, Groq, or any compatible provider.*
 
 [Getting Started](#quick-start) · [Commands](#commands) · [Configuration](#configuration) · [Contributing](#contributing) · [Security](#security-policy)
 
@@ -58,7 +58,8 @@ Most AI coding tools are built around a single vendor's model, require a browser
 | 📂 | **Repo-aware** | Explain files, search code, review diffs with full workspace context |
 | 🩹 | **Patch workflow** | Generate unified diffs, validate, preview, and apply with confirmation |
 | 🤖 | **Tool-calling agent** | `jam run` gives the model access to local tools (read, search, diff, apply) |
-| 🔌 | **Pluggable providers** | Ollama by default; adapter pattern for adding any LLM |
+| 🔌 | **Pluggable providers** | Ollama, OpenAI, Groq, **Embedded** built-in; adapter pattern for adding any LLM |
+| 📦 | **Embedded inference** | **[Experimental]** Run without Ollama — tiny GGUF model runs directly in-process via `node-llama-cpp` |
 | ⚙️ | **Layered config** | Global → repo → CLI flags; multiple named profiles |
 | 🔐 | **Secure secrets** | OS keychain via keytar, env var fallback |
 | 🐚 | **Shell completions** | Bash and Zsh |
@@ -100,14 +101,23 @@ Most AI coding tools are built around a single vendor's model, require a browser
 ### Prerequisites
 
 - **Node.js 20+**
-- **[Ollama](https://ollama.ai)** running locally (`ollama serve`)
-- A pulled model: `ollama pull llama3.2`
+- **One of the following model backends:**
+  - **[Ollama](https://ollama.ai)** running locally (`ollama serve`) + a pulled model (`ollama pull llama3.2`)
+  - **Embedded mode** — no server needed! Uses `node-llama-cpp` to run a tiny GGUF model in-process.
+    Install with: `npm install node-llama-cpp` (auto-downloads a ~250 MB model on first run)
 
 ### Install
 
 ```bash
-# Global install (once published to npm)
-npm install -g jam-cli
+# Try instantly — no install required
+npx @sunilp-org/jam-cli doctor
+
+# Global install from npm
+npm install -g @sunilp-org/jam-cli
+
+# Homebrew (macOS / Linux)
+brew tap sunilp/tap
+brew install jam-cli
 
 # Or run from source
 git clone https://github.com/sunilp/jam-cli.git
@@ -162,7 +172,9 @@ jam ask "Hello" --profile work
 | `--provider <name>` | Override provider |
 | `--base-url <url>` | Override provider base URL |
 | `--profile <name>` | Use a named config profile |
-| `--no-color` | Strip ANSI colors from output |
+| `--no-tools` | Disable read-only tool use (file discovery) |
+| `--no-color` | Strip ANSI colors from output (global flag) |
+| `-q, --quiet` | Suppress all non-essential output (spinners, status lines, decorations) |
 
 ---
 
@@ -236,6 +248,50 @@ jam diff --staged --json    # JSON output
 
 ---
 
+### `jam review`
+
+Review a branch or pull request with AI.
+
+```bash
+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:**
+
+| Flag | Description |
+|------|-------------|
+| `--base <ref>` | Base branch or ref to diff against (default: `main`) |
+| `--pr <number>` | Review a specific PR number (requires `gh` CLI) |
+| `--json` | Machine-readable JSON output |
+
+---
+
+### `jam commit`
+
+Generate an AI-written commit message from staged changes and commit.
+
+```bash
+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:**
+
+| Flag | Description |
+|------|-------------|
+| `--dry` | Generate the message but do not commit |
+| `--yes` | Auto-confirm without prompting |
+| `--amend` | Amend the last commit with a new AI-generated message |
+
+Messages follow the [Conventional Commits](https://conventionalcommits.org) specification.
+
+---
+
 ### `jam patch`
 
 Ask the AI to generate a unified diff patch, validate it, and optionally apply it.
@@ -278,6 +334,7 @@ jam run "Read src/config.ts and identify any security issues"
 | `git_diff` | Read | Get git diff |
 | `write_file` | **Write** | Write to a file (prompts for confirmation) |
 | `apply_patch` | **Write** | Apply a unified diff (prompts for confirmation) |
+| `run_command` | **Write** | Execute a shell command (dangerous patterns blocked; prompts for confirmation) |
 
 Write tools require confirmation unless `toolPolicy` is set to `allowlist` in config.
 
@@ -302,6 +359,18 @@ 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.
+
+```bash
+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`
 
 ```bash
@@ -356,12 +425,16 @@ Checks:
 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
+1. CLI flags                              (--provider, --model, etc.)
+2. .jam/config.json  or  .jamrc           (repo-level)
+3. ~/.jam/config.json                     (user home-dir dotfile — preferred)
+4. ~/.config/jam/config.json              (XDG user config — fallback)
+5. Built-in defaults
 ```
 
+> **Recommended:** Use `~/.jam/config.json` for your personal settings (provider, API keys, default model).  
+> Use `.jam/config.json` at the repo root for project-specific overrides (tool policy, redact patterns).
+
 ### Config Schema
 
 ```json
@@ -380,6 +453,10 @@ Jam merges config in priority order (highest wins):
       "provider": "ollama",
       "model": "qwen2.5-coder:1.5b",
       "baseUrl": "http://localhost:11434"
+    },
+    "embedded": {
+      "provider": "embedded",
+      "model": "smollm2-360m"
     }
   },
   "toolPolicy": "ask_every_time",
@@ -406,7 +483,7 @@ Jam merges config in priority order (highest wins):
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `provider` | string | Provider name (`ollama`) |
+| `provider` | string | Provider name (`ollama`, `openai`, `groq`, `embedded`) |
 | `model` | string | Model ID (e.g. `llama3.2`, `codellama`) |
 | `baseUrl` | string | Provider API base URL |
 | `apiKey` | string | API key (prefer keychain or env vars) |
@@ -417,11 +494,43 @@ Jam merges config in priority order (highest wins):
 ### Initialize Config
 
 ```bash
-# Repo-level (committed to version control)
+# User-level — creates ~/.jam/config.json (recommended)
+jam config init --global
+
+# Repo-level — creates .jam/config.json (committed to version control)
 jam config init
+```
 
-# User-level (applies everywhere)
-jam config init --global
+The global config at `~/.jam/config.json` is the best place to set your default provider, model, API keys, and personal preferences. Edit it directly:
+
+```bash
+# Example: switch default provider to embedded
+vim ~/.jam/config.json
+```
+
+```json
+{
+  "defaultProfile": "default",
+  "profiles": {
+    "default": {
+      "provider": "ollama",
+      "model": "llama3.2",
+      "baseUrl": "http://localhost:11434"
+    },
+    "openai": {
+      "provider": "openai",
+      "model": "gpt-4o-mini",
+      "apiKey": "sk-..."
+    },
+    "offline": {
+      "provider": "embedded",
+      "model": "smollm2-360m"
+    }
+  },
+  "toolPolicy": "ask_every_time",
+  "historyEnabled": true,
+  "logLevel": "warn"
+}
 ```
 
 ### Using Profiles
@@ -442,6 +551,74 @@ echo '{"defaultProfile": "fast"}' > .jamrc
 |----------|-------------|
 | `JAM_API_KEY` | API key fallback (if keytar unavailable) |
 | `JAM_BASE_URL` | Override provider base URL |
+| `OPENAI_API_KEY` | OpenAI API key (used when `provider: openai`) |
+| `GROQ_API_KEY` | Groq API key (used when `provider: groq`) |
+
+---
+
+## Embedded Provider — Experimental ⚗️
+
+> **⚠️ EXPERIMENTAL** — The embedded provider is functional but quality is limited by small model sizes. For production workloads, use Ollama or OpenAI.
+
+The `embedded` provider runs a tiny GGUF model **directly in-process** via [`node-llama-cpp`](https://github.com/withcatai/node-llama-cpp). No Ollama installation, no server process, no network calls. **Models are only downloaded when you explicitly set `provider: "embedded"`** — it never downloads anything unless you opt in.
+
+### Setup
+
+```bash
+# Install the native dependency (optional — only needed for embedded mode)
+npm install node-llama-cpp
+
+# Switch to embedded provider
+jam ask "Hello" --provider embedded
+
+# Or set it permanently in your config
+jam config init --global   # then edit ~/.jam/config.json
+```
+
+### How It Works
+
+1. On first use, Jam auto-downloads a small model (~250 MB) to `~/.jam/models/`
+2. The model loads in-process using llama.cpp bindings — no external server
+3. Streaming, tool-calling, and all standard commands work as usual
+
+### Available Models
+
+| Alias | Size (Q4_K_M) | Notes |
+|-------|---------------|-------|
+| `smollm2-135m` | ~100 MB | Ultra-light, very fast, basic quality |
+| `smollm2-360m` | ~250 MB | **Default** — good quality-to-size ratio |
+| `smollm2-1.7b` | ~1 GB | Best quality for embedded, needs more RAM |
+
+```bash
+# Use a specific embedded model alias
+jam ask "Explain git rebase" --provider embedded --model smollm2-1.7b
+
+# Or point to any local GGUF file
+jam ask "Hello" --provider embedded --model /path/to/custom-model.gguf
+
+# Profile-based setup
+# In ~/.jam/config.json:
+# {
+#   "profiles": {
+#     "offline": {
+#       "provider": "embedded",
+#       "model": "smollm2-1.7b"
+#     }
+#   }
+# }
+jam ask "Hello" --profile offline
+```
+
+### When to Use Embedded vs Ollama
+
+| Scenario | Recommendation |
+|----------|---------------|
+| No Ollama / can't install system software | **Embedded** |
+| CI/CD pipeline, Docker container, SSH box | **Embedded** |
+| Air-gapped / offline machine | **Embedded** (after initial model download) |
+| Want best quality & larger models (7B+) | **Ollama** |
+| GPU acceleration needed | **Ollama** |
+| Already have Ollama running | **Ollama** |
 
 ---
 
@@ -461,50 +638,14 @@ npm run test:coverage                 # coverage report
 
 ```
 src/
-├── index.ts              # CLI entry point (commander, lazy imports)
-├── commands/             # One file per command
-│   ├── ask.ts            # jam ask
-│   ├── chat.ts           # jam chat
-│   ├── run.ts            # jam run (agentic loop)
-│   ├── explain.ts        # jam explain
-│   ├── search.ts         # jam search
-│   ├── diff.ts           # jam diff
-│   ├── patch.ts          # jam patch
-│   ├── auth.ts           # jam auth
-│   ├── config.ts         # jam config
-│   ├── models.ts         # jam models
-│   ├── history.ts        # jam history
-│   ├── completion.ts     # jam completion
-│   └── doctor.ts         # jam doctor
-├── providers/            # LLM adapter layer
-│   ├── base.ts           # ProviderAdapter interface
-│   ├── ollama.ts         # Ollama adapter (NDJSON streaming)
-│   └── factory.ts        # createProvider()
-├── tools/                # Model-callable local tools
-│   ├── types.ts          # ToolDefinition, ToolResult interfaces
-│   ├── registry.ts       # ToolRegistry + permission enforcement
-│   ├── read_file.ts
-│   ├── list_dir.ts
-│   ├── search_text.ts
-│   ├── git_diff.ts
-│   ├── git_status.ts
-│   ├── apply_patch.ts
-│   └── write_file.ts
-├── config/               # Config loading and schema
-│   ├── schema.ts         # Zod schema
-│   ├── defaults.ts       # Built-in defaults
-│   └── loader.ts         # cosmiconfig + deep merge
-├── storage/
-│   └── history.ts        # Chat session persistence (JSON files)
-├── ui/
-│   ├── chat.tsx          # Ink chat REPL (React TUI)
-│   └── renderer.ts       # Markdown + streaming renderer
-└── utils/
-    ├── errors.ts         # JamError class
-    ├── stream.ts         # withRetry, collectStream
-    ├── logger.ts         # Logger (stderr, redaction)
-    ├── secrets.ts        # keytar + env fallback
-    └── workspace.ts      # Git root detection
+├── 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, Embedded 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
 ```
 
 ---
@@ -584,17 +725,244 @@ We take security seriously. If you discover a vulnerability, please **do not** o
 
 ## Roadmap
 
-- [ ] OpenAI / Azure OpenAI provider
+- [x] OpenAI provider
+- [ ] Azure OpenAI provider
 - [ ] Anthropic Claude provider
-- [ ] Groq provider
-- [ ] `jam commit` — AI-generated commit messages
-- [ ] `jam review` — PR review workflow
+- [x] 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
+
+```yaml
+# .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
+```
+
+```bash
+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
+
+```bash
+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
+
+```json
+// .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](https://modelcontextprotocol.io) 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
+
+```json
+{
+  "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
+
+```typescript
+// .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
+
+```bash
+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:

package/dist/commands/ask.d.ts

@@ -3,7 +3,11 @@ export interface AskOptions extends CliOverrides {
     file?: string;
     json?: boolean;
     noColor?: boolean;
+    quiet?: boolean;
     system?: string;
+    /** Enable read-only tool use so the model can discover and read files.
+     *  Defaults to true when stdout is a TTY and the provider supports chatWithTools. */
+    tools?: boolean;
 }
 export declare function runAsk(inlinePrompt: string | undefined, options: AskOptions): Promise<void>;
 //# sourceMappingURL=ask.d.ts.map

package/dist/commands/ask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/commands/ask.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAcD,wBAAsB,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAyEjG"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/commands/ask.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGxD,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;yFACqF;IACrF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA0CD,wBAAsB,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAyQjG"}