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

Command	Purpose
context <query>	Start here. Composed query across flex, heat, chains, sessions, timeline, co-access
query <subcommand>	Targeted queries (flex, heat, chains, etc.)
intel health	Check intel service health
intel name-chain <id>	Name a chain using AI
daemon status	Show daemon sync state + registration
daemon once	Run a single sync cycle

Query Subcommands

Command	Purpose
query flex --files "*pattern*"	Find files by path pattern
query flex --time 7d	Find files touched in time window
query heat --time 30d	File heat metrics (specificity, velocity, score, level)
query co-access <file>	Find files accessed together
query session <id>	All files in a session
query sessions --time 7d	Session-grouped data
query chains	List conversation chains
query timeline --time 7d	Timeline data for visualization
query verify <receipt>	Verify a previous query result
query receipts	List recent query receipts

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:

Need	Use
"What's happening with project X?"	context "X"
"What files are hot right now?"	query heat
"Find files matching a pattern"	query flex --files
"What did I work on this week?"	query flex --time 7d
"Show me session history"	query sessions
"What files go with this one?"	query co-access <file>

---

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

Need	Use
Structural queries (hubs, clusters, orphans, traversal)	graph-exec or MCP
Simple file search by name	Glob
Content search	Grep
File activity/heat over time	context-os query heat
Co-access patterns	context-os query co-access
Full project context	context-os context

---

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

Need	Tool
Broad project context	context-os context "<topic>"
Find files by path pattern	context-os query flex --files
File heat/activity metrics	context-os query heat
Find files by content	Grep
Read file contents	Read
Find files by name glob	Glob
Check recent changes	git log

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

Helps	Doesn't Help
"What files did I touch for project X?"	"What was I thinking about?"
"When was this file last accessed?"	"Why did I make this change?"
"What files are related to this one?"	"What's the best architecture for X?"
"What's the status of this work?"	"How should I fix this bug?"
"What files are hot/cold right now?"	"What's in my calendar?"

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

Command	Purpose
query search <term>	Keyword search in file paths
query file <path>	History for specific file
query co-access <path>	Files accessed with target
query chains	List conversation chains
query verify <receipt>	Verify a receipt
query receipts	List recent receipts

All support --format json.

Non-Query Commands

Command	Purpose
sync-git	Sync git commits from repository
parse-sessions	Parse JSONL session files
build-chains	Build chain graph from sessions
index-files	Build inverted file index
watch	Watch directory for file changes
daemon once	Run single sync cycle
daemon start	Start daemon (foreground)
daemon status	Show sync state + registration
daemon install	Install daemon to run on login
daemon uninstall	Remove daemon from login
intel health	Check intel service health
intel name-chain <id>	Name a chain using AI
serve	Start HTTP API server

---

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.)