CLI-first code context and analysis for agent workflows. Use when an agent needs deterministic local project understanding, semantic context retrieval, AST pattern search, debug-context extraction from logs, embeddings lifecycle management, context-pack workflows, or MCP-to-CLI migration mapping via the `ambiance` command.
Versioned skill templates for CLI-first agent workflows.
New to Ambiance? Start here:
Machine-readable source of truth (recommended for agents):
ambiance skill list --jsonambiance skill workflow <name> --jsonambiance skill recipe <name> --jsonCLI help discovery (quickest way to inspect command flags):
ambiance --helpambiance --help --expandedambiance <command> --help (examples: ambiance context --help, ambiance embeddings --help)This document provides comprehensive command reference, output schemas, and workflow examples.
Before the first investigation or when the environment changes, verify the CLI:
# 1. Verify CLI installation and environment
ambiance doctor --json
# 2. Validate skill templates
ambiance skill verify --json
Default policy: choose adaptively. Use context --format index --no-embeddings when exact identifiers are known. Use context --format index --embeddings for conceptual or cross-system questions, then turn the discovered chunk symbols into one deterministic follow-up query.
| Task | Command | When to Use | Embeddings |
|------|---------|------------|------------|
| Check environment | doctor | First run, troubleshooting | No |
| Project overview | hints | First time in codebase, navigation | No |
| Discover an unfamiliar behavior | context "<query>" --format index --embeddings | Semantic frontier across modules | Yes |
| Understand known symbols | context "<symbols>" --no-embeddings | Focused deterministic evidence | No |
| Navigate to exact locations | context "<query>" --format index --no-embeddings | Low-token file:line targets | No |
| Debug an error | debug "<log>" | Extract context from error logs | Optional |
| Find AST structures | grep "<pattern>" | Structural/capture-based search after index navigation | No |
| Fill exact text details | native rg -n "<term>" | String-level verification in files selected by index/grep | No |
| Analyze frontend | frontend | UI component analysis | No |
| Single file summary | summary <file> | Quick file overview | No |
| Manage embeddings | embeddings <action> | Setup, maintenance, status checks | N/A |
| Context packs | packs <action> | Save/load reusable context | No |
| Cross-agent continuity | handoff [action] | List Codex/Claude sessions and create portable handoffs | No |
Use this order for agent search decisions:
context --format index --no-embeddings query.context --format index --embeddings semantic frontier.grep, summary, and native rg -n only for the selected files and ranges.Use at most one bounded search scout after these steps leave a specific unresolved question. Multi-agent search is not the default navigation strategy.
For the first semantic frontier, describe one behavior or system boundary in plain language. For the deterministic follow-up, use the exact identifiers returned by the semantic chunks.
Examples:
background cleanup during process shutdownstartCleanupTimer disposeAll process.once cleanupmachine-readable CLI output while installing the skillrunSkillInstall isJsonMode quiet SkillInstallReportUse this maintenance order:
ambiance embeddings status --json --project-path ./ambiance context "<query>" --json --project-path ./ --embeddings
or ambiance embeddings update --json --project-path ./
Incremental freshness repairs new, stale, deleted, and tracked zero-chunk files.ambiance embeddings create --json --project-path ./ --force true for migration/incompatible-model/corruption scenarios.doctor - Environment DiagnosticsPurpose: Verify CLI installation, environment variables, and project readiness.
Usage:
ambiance doctor --json
Output Schema:
{
"success": true,
"timestamp": "2026-02-06T22:56:22.919Z",
"node": {
"version": "v22.12.0",
"platform": "win32",
"arch": "x64"
},
"workspace": {
"detectedProjectPath": "C:\\path\\to\\project"
},
"embeddings": {
"useLocalEmbeddings": "true",
"sqliteBindings": {
"available": true
}
},
"dependencies": {
"treeSitter": { "available": true },
"transformers": { "available": true }
}
}
hints - Project Structure AnalysisPurpose: Get high-level project structure, key files, and navigation hints.
Usage:
ambiance hints --json --project-path ./ --max-files 50
Output Schema:
{
"projectType": "typescript-node",
"entryPoints": ["src/index.ts", "src/cli.ts"],
"keyDirectories": {
"source": "src/",
"tests": "tests/",
"config": "./"
},
"technologies": ["typescript", "jest", "node"],
"fileCount": 234,
"hints": [
"Main entry point: src/index.ts",
"CLI entry point: src/cli.ts",
"Test files in tests/ directory"
]
}
When to use:
context - Semantic Code ContextPurpose: Generate compact, semantically relevant code context for a query.
Usage:
ambiance context "authentication flow" --json --project-path ./ --max-tokens 2000
Output Schema:
{
"query": "authentication flow",
"summary": "Authentication is handled through JWT tokens with middleware validation...",
"relevantFiles": [
{
"path": "src/auth/middleware.ts",
"relevance": 0.95,
"snippet": "export function validateToken(req, res, next) {...}",
"lineRange": [12, 45]
}
],
"totalTokens": 1847,
"truncated": false
}
When to use:
Task types:
--task-type implement: Focus on implementation details--task-type review: Focus on architecture and patternsOutput formats:
--format json (default): Semantic compression for LLM context--format index: Code navigation with jump points (see below)--format index)The index format transforms context into a code navigation tool, returning structured jump points instead of compressed summaries.
Usage:
ambiance context "authentication" --format index --project-path ./ --max-tokens 2000
Output Schema:
{
"jumpTargets": [
{
"file": "C:\\path\\to\\src\\auth.ts",
"symbol": "validateToken",
"start": 42,
"end": 89,
"role": "interface",
"confidence": 0.9,
"relevance": 0.85,
"why": ["export name matches: validateToken"],
"snippet": "export function validateToken(req, res, next) {\n const token = req.headers.authorization;\n ..."
}
],
"byFile": {
"src/auth.ts": [
{"symbol": "validateToken", "start": 42, "confidence": 0.9, ...}
],
"src/middleware.ts": [
{"symbol": "authMiddleware", "start": 12, "confidence": 0.8, ...}
]
},
"answerDraft": "Authentication uses JWT tokens with validateToken function...",
"nextActions": {
"mode": "code_lookup",
"openFiles": ["src/auth.ts:42-89", "src/middleware.ts:12-34"],
"checks": ["find src/ -name \"*.md\" | head -5"]
},
"evidence": [
"validateToken @ src/auth.ts:42",
"parseToken @ src/utils.ts:15"
],
"metadata": {
"filesScanned": 278,
"symbolsConsidered": 20,
"bundleTokens": 1958,
"processingTimeMs": 1027,
"roleDistribution": {
"interface": 5,
"operation": 14,
"dependency": 1
}
}
}
Key fields:
jumpTargets: Array of code locations with precise file:line ranges
role: interface (exports, 90% confidence), operation (calls, 70%), or dependency (imports, 80%)confidence: Score from 0.0 to 1.0 indicating match quality (AST-based)relevance: Score from 0.0 to 1.0 indicating query importance (semantic-based)snippet: Code preview (5-10 lines) extracted from the filewhy: Explanation of why this location matchedbyFile: Jump targets grouped by file path (easier navigation)nextActions.openFiles: Top 3-5 files to examine nextevidence: Quick reference list of symbol@file:linemetadata.roleDistribution: Count of results by role (interface/operation/dependency)When to use index format:
rg or manual file inspection before AST searchesWhen to use JSON format:
Example workflows:
// 1. Filter by both confidence AND relevance for best results
const index = runAmbiance(['context', 'auth', '--format', 'index', '--project-path', './']);
const bestResults = index.jumpTargets.filter(
t => t.confidence >= 0.85 && t.relevance >= 0.7
);
// 2. Navigate by file (open one file, jump to multiple symbols)
Object.entries(index.byFile).forEach(([file, targets]) => {
console.log(`${file}: ${targets.length} symbols`);
targets.forEach(t => console.log(` - ${t.symbol} at line ${t.start}`));
});
// 3. Preview code before opening
const topTarget = index.jumpTargets[0];
console.log(`Preview:\n${topTarget.snippet}`);
if (isRelevant(topTarget.snippet)) {
openInEditor(topTarget.file, topTarget.start);
}
// 4. Check result composition
const { interface, operation, dependency } = index.metadata.roleDistribution;
console.log(`Found ${interface} definitions, ${operation} usages, ${dependency} imports`);
debug - Debug Context ExtractionPurpose: Extract likely root causes and related code from error logs.
Usage:
ambiance debug "TypeError: Cannot read property 'token' of undefined at auth.ts:42" \
--json --project-path ./
Output Schema:
{
"parsedError": {
"type": "TypeError",
"message": "Cannot read property 'token' of undefined",
"file": "auth.ts",
"line": 42
},
"likelyFiles": [
"src/auth.ts",
"src/middleware/jwt.ts"
],
"relatedFunctions": [
"validateToken",
"parseAuthHeader"
],
"context": {
"files": [
{
"path": "src/auth.ts",
"relevantLines": [[38, 50]],
"snippet": "..."
}
]
},
"suggestions": [
"Check if parseAuthHeader returns null",
"Add null check before accessing token property"
]
}
When to use:
grep - AST-Based Structural SearchPurpose: Find code patterns using Abstract Syntax Tree matching.
Usage:
ambiance grep "function \$NAME(\$ARGS) { \$BODY }" \
--json --project-path ./ --language typescript
# Rule-mode (file)
ambiance grep --rule-path ./rules/no-console.yml \
--json --project-path ./ --language typescript
# Rule-mode (inline JSON)
ambiance grep --rule-json '{"id":"no-console","language":"typescript","rule":{"pattern":"console.$METHOD($ARGS)"}}' \
--json --project-path . --file-pattern "src/**/*.ts"
# PowerShell: prefer single quotes so $ metavariables are not expanded
ambiance grep 'function $NAME($ARGS) { $BODY }' --json --project-path . --language typescript
Output Schema:
{
"pattern": "function $NAME($ARGS) { $BODY }",
"language": "typescript",
"matches": [
{
"file": "src/utils.ts",
"line": 15,
"match": "function parseToken(header: string) { return header.split(' ')[1]; }",
"captures": {
"NAME": "parseToken",
"ARGS": "header: string",
"BODY": "return header.split(' ')[1];"
}
}
],
"totalMatches": 23,
"engineUsed": "ast-grep",
"degraded": false
}
When to use:
frontend - Frontend Pattern AnalysisPurpose: Analyze frontend code patterns, components, and UI structure.
Usage:
ambiance frontend --json --project-path ./
When to use:
summary - Single File SummaryPurpose: Get AST-based summary of a single file.
Usage:
ambiance summary src/auth.ts --json
Output Schema:
{
"file": "src/auth.ts",
"language": "typescript",
"exports": ["validateToken", "parseAuthHeader", "AuthMiddleware"],
"imports": ["jsonwebtoken", "express"],
"functions": [
{
"name": "validateToken",
"line": 12,
"parameters": ["req", "res", "next"],
"async": false
}
],
"classes": [],
"interfaces": ["AuthRequest"],
"complexity": "medium"
}
When to use:
embeddings - Embedding ManagementPurpose: Manage semantic embeddings for the project.
Actions:
status: Check embedding statuscreate: Generate embeddings for the projectupdate: Refresh stale embeddingsvalidate: Verify embedding integrityUsage:
# Check status
ambiance embeddings status --json --project-path ./
# Create embeddings
ambiance embeddings create --json --project-path ./ --force true
# Update stale embeddings
ambiance embeddings update --json --project-path ./
Status Output Schema:
{
"command": "embeddings",
"exitCode": 0,
"success": true,
"projectId": "86bc5cbe7850",
"projectPath": "C:\\path\\to\\project",
"stats": {
"totalChunks": 3000,
"totalFiles": 183,
"lastUpdated": "2026-02-12T13:25:19.000Z"
},
"coverage": {
"embeddedFiles": 184,
"indexableFiles": 241,
"coveragePercent": 76.35
}
}
packs - Context Pack WorkflowsPurpose: Create, manage, and reuse context packs for common scenarios.
Actions: create, list, get, delete, template, ui
Usage:
# Create a context pack
ambiance packs create --name "auth-system" --json
# List available packs
ambiance packs list --json
# Get a specific pack
ambiance packs get --name "auth-system" --json
handoff - Portable Agent ContinuityPurpose: Recover locally retained Codex and Claude work as a compact, evidence-linked handoff.
The source transcript is read-only; the generated handoff is stored under ~/.ambiance/handoffs
unless AMBIANCE_HANDOFFS_DIR or --handoffs-dir overrides it.
# Numbered titles scoped to the current project
ambiance handoff list --json --project-path ./
# Compact recovery for another model or agent
ambiance handoff create 2 --compact --json --project-path ./
# Stable automation after parsing the list
ambiance handoff create --session-id <session-id> --max-tokens 4000 --json --project-path ./
# Inspect retained verification evidence without loading the whole transcript
ambiance handoff evidence <handoff-id> --tests --json
--compact targets 2,000 tokens; standard mode targets 6,000. Use --max-tokens to override.
The first handoff create in a fresh environment may take ~30s while the local embedding model
loads for code-evidence refresh; subsequent runs complete in a few seconds.
The JSON list includes both a human-friendly selection and stable sessionId. Pass the returned
listId to handoff create --list-id <id> when numbered selection must fail safely if the list changes.
Raw transcript copying is opt-in through --include-transcript because provider logs may contain secrets.
--max-tokensControls the maximum size of returned context. Choose based on use case:
Trade-off: Higher values = more complete context but slower processing and higher LLM costs.
--max-filesControls breadth of file discovery. Choose based on scope:
Trade-off: Higher values = broader coverage but slower processing.
--project-pathExplicitly specify the project directory:
--project-path for deterministic resultsWORKSPACE_FOLDER for default path# Explicit (recommended for agents)
ambiance context "auth" --json --project-path /path/to/project
# Auto-detect (may print detection message to stderr)
ambiance context "auth" --json
--task-typeInfluences context selection and summarization:
implement: Focus on implementation details, function signatures, patternsreview: Focus on architecture, design patterns, testing coverageScenario: User asks "How does authentication work in this project?"
# Step 1: Get project overview
ambiance hints --json --project-path ./
# Example output:
# {
# "projectType": "typescript-express",
# "keyDirectories": {"source": "src/", "tests": "tests/"},
# "hints": ["Authentication middleware in src/auth/"]
# }
# Step 2: Get semantic context for authentication
ambiance context "authentication and authorization" \
--json --project-path ./ --max-tokens 3000
# Example output:
# {
# "summary": "Authentication uses JWT tokens with Express middleware...",
# "relevantFiles": [
# {"path": "src/auth/middleware.ts", "relevance": 0.95, ...},
# {"path": "src/auth/jwt.ts", "relevance": 0.89, ...}
# ]
# }
Agent response: "The project uses JWT-based authentication implemented in src/auth/middleware.ts:12-45. The middleware validates tokens and attaches user data to requests..."
Scenario: User reports "Getting 'undefined is not a function' in production logs"
# Step 1: Extract context from error log
ambiance debug "TypeError: undefined is not a function at processRequest (api.ts:142)" \
--json --project-path ./
# Example output:
# {
# "parsedError": {"file": "api.ts", "line": 142},
# "likelyFiles": ["src/api.ts", "src/middleware/validator.ts"],
# "relatedFunctions": ["processRequest", "validateInput"],
# "suggestions": ["Check if validateInput is imported correctly"]
# }
# Step 2: Get detailed context for the problematic area
ambiance context "processRequest function and related validation" \
--json --project-path ./ --max-tokens 2000
# Example output shows the function definition and reveals the issue
Agent response: "The error occurs at src/api.ts:142 in the processRequest function. The issue is that validateInput is conditionally imported and may be undefined when..."
Scenario: User asks "Add rate limiting to the API"
# Step 1: Understand current middleware structure
ambiance hints --json --project-path ./
# Step 2: Get implementation-focused context
ambiance context "middleware and request handling" \
--json --project-path ./ --max-tokens 3000 --task-type implement
# Example output:
# {
# "relevantFiles": [
# {"path": "src/middleware/index.ts", "snippet": "app.use(cors())...", ...},
# {"path": "src/app.ts", "snippet": "Middleware registration", ...}
# ]
# }
# Step 3: Find existing middleware patterns
ambiance grep "app.use(\$MIDDLEWARE)" --json --project-path ./ --language typescript
# Example output shows all middleware registration points
Agent response: "I'll add rate limiting middleware similar to the existing CORS middleware at src/middleware/index.ts:8. Here's the implementation..."
Scenario: User asks "Review the authentication implementation for security issues"
# Step 1: Get review-focused context
ambiance context "authentication security validation error handling" \
--json --project-path ./ --max-tokens 5000 --task-type review
# Step 2: Find all authentication-related functions
ambiance grep "function \$NAME(\$ARGS) { \$BODY }" \
--json --project-path ./ --language typescript | \
# (filter for auth-related files)
# Step 3: Check frontend integration if applicable
ambiance frontend --json --project-path ./
Agent response: "Security review of authentication implementation:
src/auth/config.ts:5 - should use environment variablesrc/routes/auth.ts:12src/auth/jwt.ts:23)..."ambiance context "auth" --json --project-path ./
Error:
{
"error": "Embeddings not initialized for project",
"suggestion": "Run: ambiance embeddings create --json --project-path ./ --force true",
"fallback": "Using basic text search (results may be less accurate)"
}
Resolution: Run ambiance embeddings create --json --project-path ./ --force true
ambiance hints --json --project-path /invalid/path
Error:
{
"error": "Project path does not exist or is not accessible",
"path": "/invalid/path"
}
Resolution: Verify path exists or use --project-path ./ for current directory
ambiance context "nonexistent feature" --json --project-path ./
Output:
{
"query": "nonexistent feature",
"summary": "No relevant code found for this query",
"relevantFiles": [],
"totalTokens": 0,
"suggestions": [
"Try broader search terms",
"Check if embeddings are up to date",
"Verify spelling of technical terms"
]
}
Agent action: Rephrase query, try hints for project overview, or use grep with patterns
ambiance embeddings sta
<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer