context-os-cli

name: context-os-cli description: > This skill should be used when users ask about their work context, what they're working on, recent activity, file relationships, or knowledge graph structure. Uses context-os CLI (including graph health/search/stats commands) combined with grep/glob for context restoration. Every claim MUST cite a receipt ID for user verification.

Context OS CLI Skill

Use context-os CLI + grep + glob together for context restoration.

Core insight: The CLI finds WHICH files matter. Grep/Read find WHAT's in them.

Quick Start (90% of queries)

# 1. Full context for a topic (start here — one command does it all)
context-os context "pixee" --format json

# 2. If you need to drill deeper, use targeted queries
context-os query flex --files "*pixee*" --agg count,recency --format json

# 3. Read hot files to understand what they are
Read: <top_file_from_step_1>

# 4. Search content IN those files
Grep: pattern="hubspot|integration" path=<directory_from_step_1>

# 5. Check git for recent changes
git log --oneline -10 -- <hot_files>

Start with context for broad questions, drop to query subcommands for targeted drilldowns.

CLI Commands

Top-Level Commands

Query Subcommands

Always use --format json — table output truncates long paths.

The context Command

The highest-level query. One command gives you executive summary, heat, work clusters, insights, continuity, timeline, and suggested reads.

context-os context "tastematter" --format json
context-os context "pixee" --time 14d --format json

Response includes:

• executive_summary — status, work_tempo, hot_file_count, focus_ratio
• current_state — key_metrics, evidence (file excerpts)
• continuity — left_off_at, pending_items, chain_context
• work_clusters — co-accessed file groups with PMI scores
• suggested_reads — prioritized files (with surprise flag for unexpected)
• timeline — weekly focus areas with top files and access counts
• insights — abandoned file detection, anomalies
• verification — receipt_id, files/sessions/pairs analyzed
• quick_start — commands and directory structures from matching files

When to use context vs query:

The query heat Command

Shows file heat metrics with percentile-based classification.

context-os query heat --time 30d --format json
context-os query heat --files "*tastematter*" --sort specificity --format csv

Options:

-t, --time <TIME>      Long window: 30d (default), 14d, 60d, 90d
-f, --files <FILES>    File path pattern filter (glob-style)
-l, --limit <LIMIT>    Max results (default: 50)
-s, --sort <SORT>      Sort by: heat (default), specificity, velocity, name
    --format <FORMAT>  Output: table (default), json, compact, csv

Heat levels use percentile classification:

• Top 10% = HOT, 10-30% = WARM, 30-60% = COOL, Bottom 40% = COLD

Key fields: specificity (IDF-like), velocity, heat_score, heat_level

See references/heat-metrics-model.md for formula details and interpretation tables.

Graph Traversal: graph-exec Command

Executes JavaScript against an in-memory knowledge graph (markdown files with frontmatter + wiki-links). Uses Boa JS engine — pure Rust, no Node/bun.

context-os graph-exec --graph <path-to-markdown-dir> '<javascript-code>'

The codemode Object (4 functions, all synchronous)

codemode.graph_search({ pattern, scope?, maxResults? })
  pattern: string        — regex to match
  scope: 'content' | 'frontmatter' | 'both' (default: 'both')
  maxResults: number     (default: 20)
  Returns: [{ path, matches: [{ line, content }], score, frontmatter }]

codemode.graph_traverse({ start, direction?, maxDepth?, filter? })
  start: string          — node name (filename without .md, e.g. "context-engineering")
  direction: 'outbound' | 'inbound' | 'both' (default: 'outbound')
  maxDepth: number       (default: 2)
  filter: { status?, domain?, tags? }
  Returns: { nodes: [{ path, name, depth, frontmatter }], edges: [{ from, to }] }

codemode.graph_read({ path, section?, maxLines? })
  path: string           — relative path (e.g. "technical/context-engineering.md")
  section: string        — extract named heading section only
  Returns: { path, content, frontmatter, outbound_links, inbound_links }

codemode.graph_query({ filter, sort?, limit? })
  filter: { status?, domain?, tags?, name?, validated_by? }
  sort: 'name' | 'last_updated' | 'status'
  limit: number          (default: 50)
  Returns: { nodes: [{ path, name, status, domain, tags, last_updated, link_count }], total }

Code Pattern: Use IIFEs

Functions are synchronous (not async). Wrap code in an IIFE:

# CORRECT — IIFE returns a value
context-os graph-exec --graph 04_knowledge_base '(() => {
  const r = codemode.graph_query({ filter: { status: "canonical" } });
  return JSON.stringify({ total: r.total, names: r.nodes.map(n => n.name) });
})()'

# WRONG — bare return is a syntax error
context-os graph-exec --graph 04_knowledge_base 'return codemode.graph_search({})'

# WRONG — async not needed (and Boa doesn't support top-level await)
context-os graph-exec --graph 04_knowledge_base 'async () => { ... }'

Bash Escaping

Keep JS simple when passing inline. Avoid backslashes and nested quotes. If complex, use a heredoc:

context-os graph-exec --graph 04_knowledge_base "$(cat <<'JSEOF'
(() => {
  const hubs = codemode.graph_query({ filter: {} });
  const sorted = hubs.nodes
    .sort((a, b) => (b.link_count.outbound + b.link_count.inbound) - (a.link_count.outbound + a.link_count.inbound))
    .slice(0, 10);
  return JSON.stringify(sorted.map(n => ({
    name: n.name,
    links: n.link_count.outbound + n.link_count.inbound
  })));
})()
JSEOF
)"

Common Graph Queries

# Top hubs by link count
context-os graph-exec --graph 04_knowledge_base '(() => {
  const r = codemode.graph_query({ filter: {} });
  return JSON.stringify(r.nodes.sort((a,b) => (b.link_count.outbound+b.link_count.inbound)-(a.link_count.outbound+a.link_count.inbound)).slice(0,5).map(n => ({ name: n.name, out: n.link_count.outbound, in: n.link_count.inbound })));
})()'

# All canonical nodes
context-os graph-exec --graph 04_knowledge_base '(() => {
  const r = codemode.graph_query({ filter: { status: "canonical" } });
  return JSON.stringify({ total: r.total, nodes: r.nodes.map(n => n.name) });
})()'

# Traverse outbound from a node
context-os graph-exec --graph 04_knowledge_base '(() => {
  const r = codemode.graph_traverse({ start: "context-engineering", direction: "both", maxDepth: 1 });
  return JSON.stringify(r.nodes.map(n => ({ name: n.name, depth: n.depth })));
})()'

# Find orphan nodes (no links)
context-os graph-exec --graph 04_knowledge_base '(() => {
  const r = codemode.graph_query({ filter: {} });
  const orphans = r.nodes.filter(n => n.link_count.outbound === 0 && n.link_count.inbound === 0);
  return JSON.stringify({ count: orphans.length, nodes: orphans.map(n => n.name) });
})()'

# Search then read (composition)
context-os graph-exec --graph 04_knowledge_base '(() => {
  const results = codemode.graph_search({ pattern: "taste" });
  const top = results[0];
  const detail = codemode.graph_read({ path: top.path });
  return JSON.stringify({ path: detail.path, outbound: detail.outbound_links, inbound: detail.inbound_links });
})()'

MCP Alternative

If running inside Claude Code with the codemode-graph MCP server enabled, prefer the MCP tool over the CLI. The MCP tool description is embedded and the LLM gets the API right on the first call. Functions are async in MCP mode:

// MCP mode (async, tool description auto-loaded)
async () => {
  const results = await codemode.graph_search({ pattern: 'context' });
  return results[0];
}

When to Use graph-exec vs MCP vs grep/glob

Common Mistakes

Wrong: Expect semantic search

# DON'T - CLI searches file PATHS, not content
context-os query flex --files "*notification design*"  # Won't find anything

Right: Use CLI for paths, grep for content

# DO - Find files first, then search content
context-os query flex --files "*alert*" --format json  # Find alert-related files
Grep: pattern="notification|digest|slack" path=<results>  # Search content

Wrong: Only use CLI

# DON'T - You'll miss semantic understanding
context-os query flex --files "*hubspot*"  # Returns files but not WHAT they do

Right: Combine tools

# DO - CLI narrows, Read/Grep understands
context-os query flex --files "*hubspot*" --format json
Read: <top_result>  # Understand what the file actually does

Wrong: Skip context and go straight to query

# DON'T - You'll miss insights, clusters, and continuity
context-os query flex --files "*pixee*" --format json

Right: Start broad, drill down

# DO - Get the full picture first
context-os context "pixee" --format json
# THEN drill into specific areas if needed
context-os query heat --files "*pixee*" --format json

Combining Tools

Workflow pattern:

context → full picture (summary, heat, clusters, insights)
    ↓
query heat/flex → drill into specific files or patterns
    ↓
Read → understand what files contain
    ↓
Grep → find specific concepts in content
    ↓
git log → understand evolution

Database Location

Canonical: ~/.context-os/context_os_events.db

If queries return empty results:

# Check database exists
ls ~/.context-os/context_os_events.db

# Check daemon status
context-os daemon status

# Run a single sync
context-os daemon once

# Rebuild indexes if needed
context-os build-chains
context-os index-files

Citation Requirements

Every claim from query results MUST include receipt ID:

Found 147 Pixee files [q_7f3a2b]
To verify: context-os query verify q_7f3a2b

When This Skill Helps vs Doesn't

For semantic understanding, READ the files. The CLI tells you which ones matter.

References

For advanced patterns:

• references/heat-metrics-model.md - Heat formula: specificity, exponential decay, percentile classification
• references/search-strategies.md - 9 multi-step search strategies (Pilot Drilling, Triangulation, etc.)
• references/query-patterns.md - Path substring patterns and result interpretation

CLI Full Reference

context (Composed Query — Start Here)

context-os context <QUERY> [OPTIONS]

ARGUMENTS:
  <QUERY>            Search query (used as glob pattern *query*)

OPTIONS:
  -t, --time <TIME>      Time window (default: 30d)
  -l, --limit <LIMIT>    Max results per sub-query (default: 20)
      --format <FORMAT>  Output: json (default), compact, table

query flex (Targeted File Query)

context-os query flex [OPTIONS]

OPTIONS:
  -f, --files <FILES>      File pattern (glob): "*pixee*", "*.py"
  -t, --time <TIME>        Time window: 7d (default), 14d, 30d
  -c, --chain <CHAIN>      Filter by chain ID
  -s, --session <SESSION>  Filter by session ID
  -a, --agg <AGG>          Aggregations: count, recency
  -l, --limit <LIMIT>      Max results (default: 20)
      --sort <SORT>        Order: count (default), recency
      --format <FORMAT>    Output: json (default), compact

query heat (File Heat Metrics)

context-os query heat [OPTIONS]

OPTIONS:
  -t, --time <TIME>      Window: 30d (default), 14d, 60d, 90d
  -f, --files <FILES>    File pattern filter (glob-style)
  -l, --limit <LIMIT>    Max results (default: 50)
  -s, --sort <SORT>      Sort: heat (default), specificity, velocity, name
      --format <FORMAT>  Output: table (default), json, compact, csv

query timeline (Visualization Data)

context-os query timeline [OPTIONS]

OPTIONS:
  -t, --time <TIME>      Time range: 7d (default), 14d, 30d
  -p, --files <FILES>    File pattern filter
  -c, --chain <CHAIN>    Filter by chain ID
  -l, --limit <LIMIT>    Max files (default: 30)
      --format <FORMAT>  Output: json (default), compact

query sessions (Session-Grouped)

context-os query sessions [OPTIONS]

OPTIONS:
  -t, --time <TIME>      Time range: 7d (default), 14d, 30d
  -c, --chain <CHAIN>    Filter by chain ID
  -l, --limit <LIMIT>    Max sessions (default: 50)
      --format <FORMAT>  Output: json (default), compact

Other Query Commands

All support --format json.

Non-Query Commands

Last Updated: 2026-04-07 Version: 6.0 (Renamed from context-query to context-os-cli. All local CLI commands now reference context-os binary. Publishing commands remain tastematter. Added graph health/search/stats from Spec 32.)