cleveragents-core/docs/reference/project_context_cli.md

Project Context CLI Reference

The agents project context commands manage per-project context policies that control what resources and files are visible during each ACMS phase, and provide tools to inspect and simulate the ACMS pipeline state.

Overview

Context policies use view inheritance:

Phase	Inherits from
default	(none)
strategize	default
execute	strategize
apply	execute

An empty policy defaults to including everything.

---

agents project context set

Persist a context policy view and ACMS pipeline configuration for a project.

Usage

agents project context set PROJECT [OPTIONS]

Arguments

Argument	Description
PROJECT	Project namespaced name

Options

View Options

Option	Type	Description
--view, -v	str	Phase view: default, strategize, execute, apply (default: default)
--include-resource	str	Resource pattern to include (repeatable)
--exclude-resource	str	Resource pattern to exclude (repeatable)
--include-path	str	File path glob to include (repeatable)
--exclude-path	str	File path glob to exclude (repeatable)
--max-file-size	int	Max file size in bytes (None = no limit)
--max-total-size	int	Max total context size in bytes
--clear	flag	Clear (reset) the view for the phase

ACMS Pipeline Options

Option	Type	Default	Description
--hot-max-tokens	int	8000	Max tokens for the hot tier context window
--warm-max-decisions	int	500	Max decisions for the warm tier
--cold-max-decisions	int	5000	Max decisions for the cold tier
--query-limit	int	None	Max number of fragments per query
--summarize/--no-summarize	bool	True	Enable or disable context summarization
--summary-max-tokens	int	None	Max tokens for context summaries
--strategy	str	(none)	Preferred context strategy (repeatable)
--default-breadth	int	2	Default breadth for context retrieval
--default-depth	str	3	Default depth (integer or named level)
--skeleton-ratio	float	0.2	Skeleton compression ratio (0.0-1.0)
--temporal-scope	str	current	Temporal scope: current, recent, or all
--auto-refresh/--no-auto-refresh	bool	True	Auto-refresh context on resource changes

Output Options

Option	Type	Description
--format, -f	str	Output format (json, yaml, plain, table, rich)

Examples

# Set default view with resource filters
agents project context set local/my-app \
  --view default \
  --include-resource "db-*" \
  --exclude-resource "db-test"

# Set strategize view with path filters
agents project context set local/my-app \
  --view strategize \
  --include-path "src/**/*.py" \
  --exclude-path "*.pyc"

# Set size limits
agents project context set local/my-app \
  --max-file-size 1048576 \
  --max-total-size 10485760

# Clear execute view (inherit from strategize)
agents project context set local/my-app --view execute --clear

# Configure ACMS pipeline options
agents project context set local/my-app \
  --hot-max-tokens 4000 \
  --warm-max-decisions 200 \
  --temporal-scope recent \
  --no-auto-refresh

# Set preferred strategies
agents project context set local/my-app \
  --strategy breadth_first \
  --strategy depth_first

# Adjust skeleton compression
agents project context set local/my-app \
  --skeleton-ratio 0.5 \
  --default-breadth 5 \
  --default-depth 7

---

agents project context show

Display the context policy and ACMS pipeline configuration for a project.

Usage

agents project context show PROJECT [OPTIONS]

Arguments

Argument	Description
PROJECT	Project namespaced name

Options

Option	Type	Description
--view, -v	str	Show resolved view for a specific phase
--format, -f	str	Output format (json, yaml, plain, table, rich)

Output

The show command displays:

• View configuration for each phase (or the resolved view for a specific phase)
• ACMS Pipeline Config including hot/warm/cold tier budgets, summarization settings, strategies, temporal scope, and auto-refresh status

Examples

# Show all views and ACMS config
agents project context show local/my-app

# Show resolved view for execute phase
agents project context show local/my-app --view execute

# JSON output (includes acms_config key)
agents project context show local/my-app --format json

---

agents project context inspect

Inspect the effective context state for a project by querying the ACMS tier service. Displays current fragment distribution across tiers, tier metrics, budget utilisation, and per-actor visibility.

Usage

agents project context inspect PROJECT [OPTIONS]

Arguments

Argument	Description
PROJECT	Project namespaced name

Options

Option	Type	Description
--view, -v	str	Phase view to inspect
--strategy	str	Filter fragments by strategy name
--focus	str	UKO URIs to focus on (repeatable)
--breadth	int	Override breadth for context retrieval
--depth	str	Override depth (integer or named level)
--format, -f	str	Output format (json, yaml, plain, table, rich)

Output

The inspect command displays:

• Tier Metrics — project-scoped hot/warm/cold fragment counts, service-level hit/miss rates
• Tier Budget — configured max tokens (hot) and max decisions (warm, cold)
• Project Fragments — total count and breakdown by tier for the project
• Actor Visibility — how many fragments each actor role (strategist, executor, reviewer) can see
• Fragment Details — first 20 fragments with IDs, tiers, token counts, and access metadata
• ACMS Config — the project's pipeline configuration

Examples

# Inspect all tiers for a project
agents project context inspect local/my-app

# Inspect with JSON output
agents project context inspect local/my-app --format json

# Inspect a specific phase view
agents project context inspect local/my-app --view strategize

---

agents project context simulate

Run a dry-run context window assembly for a project. Creates a simulated AssembledContext using the project's ACMS configuration and available tier fragments.

Usage

agents project context simulate PROJECT [OPTIONS]

Arguments

Argument	Description
PROJECT	Project namespaced name

Options

Option	Type	Description
--view, -v	str	Phase view for simulation
--budget	int	Token budget override
--focus	str	UKO URIs to focus on (repeatable)
--strategy	str	Preferred strategies (repeatable)
--format, -f	str	Output format (json, yaml, plain, table, rich)

Output

The simulate command displays:

• Summary — total tokens, budget usage percentage, strategies used, fragment count, context hash
• Fragment Table — each assembled fragment with UKO node, token count, relevance score, depth, and strategy. When --focus is provided, only fragments matching the focus URIs are included.
• ACMS Config — the project's pipeline configuration used for the simulation

Examples

# Simulate with default settings
agents project context simulate local/my-app

# Simulate with custom budget
agents project context simulate local/my-app --budget 4000

# Simulate for a specific phase with strategy hints
agents project context simulate local/my-app \
  --view strategize \
  --strategy breadth_first

# JSON output for programmatic consumption
agents project context simulate local/my-app --format json