vshx

Local CLI runtime for agents and operators, powered by V.

Positioning

vshx turns local CLI tools into structured execution capabilities for humans and agents.

The current product direction is:

• run local CLI commands through a controlled runtime
• capture execution as typed events
• render output as markdown or ndjson
• support optional streaming output for both formats
• expose the same capabilities through CLI, task runtime, and stdio MCP

In the broader stack:

• vphp is the PHP/V bridge runtime
• vhttpd is the online transport/runtime
• vshx is the local CLI/tool runtime

Quick start

cd vshx
v run ./cmd/vshx --help

Build a local binary:

cd vshx
v run build.v
./bin/vshx --help

Or with make:

cd vshx
make build
make run
make mcp-inspect
make smoke

Try it

Render a one-shot command as Markdown:

v run ./cmd/vshx run --format markdown -- echo hello

Use the markdown-first Git entrypoint:

v run ./cmd/vshx git status --cwd ..
v run ./cmd/vshx git diff --cwd ..
v run ./cmd/vshx git log --cwd .. --limit 5
v run ./cmd/vshx git show --cwd .. --revision HEAD

Include raw Git output when you want the structured summary and the original transcript together:

v run ./cmd/vshx git status --cwd .. --transcript

Human + agent examples for git.readonly:

# human: compact working tree summary
v run ./cmd/vshx git status --cwd ..

# agent: stable per-file status entries
v run ./cmd/vshx git status --cwd .. --format json
# read structured_output.status_entries_json

# human: compact file-level diff summary
v run ./cmd/vshx git diff --cwd ..

# agent: stable diff entries without patch bodies
v run ./cmd/vshx git diff --cwd .. --format json
# read structured_output.diff_entries_json

Use the markdown-first ripgrep entrypoint:

v run ./cmd/vshx rg shell.exec --cwd vshx/core/runtime
v run ./cmd/vshx rg policy --cwd . --path vshx/core --limit 20

Human + agent examples for rg.search:

# human: grouped markdown search view
v run ./cmd/vshx rg shell.exec --cwd vshx/core/runtime

# agent: flattened search summary + match events
v run ./cmd/vshx rg shell.exec --cwd vshx/core/runtime --format json
# read structured_output.match_count, matched_files, matches

Stream typed execution events as NDJSON:

v run ./cmd/vshx run --format ndjson --stream -- git status --short

Stream a command as Markdown in a terminal-style view:

v run ./cmd/vshx run --format markdown --stream -- tail -f app.log

Override the default risk policy for an intentional high-risk command shape:

v run ./cmd/vshx run --format markdown --allow-risky -- sh -lc 'echo hello'

Inspect the tool registry:

v run ./cmd/vshx tool list
v run ./cmd/vshx tool describe git.readonly
v run ./cmd/vshx tool describe rg.search
v run ./cmd/vshx tool describe shell.exec
v run ./cmd/vshx tool call rg.search --query shell.exec --cwd vshx/core/runtime
v run ./cmd/vshx tool call git.readonly --op status --cwd ..
v run ./cmd/vshx tool call shell.exec -- echo hello

Agent-native examples for tool call:

# call a tool directly and get the full TaskResult JSON
v run ./cmd/vshx tool call git.readonly --op diff --cwd ..

# call search directly and consume structured_output / events
v run ./cmd/vshx tool call rg.search --query shell.exec --cwd vshx/core/runtime

# call shell.exec directly when you want generic local execution
v run ./cmd/vshx tool call shell.exec -- echo hello

Persist a command execution as a task record:

v run ./cmd/vshx task run shell.exec -- echo hello

Operator examples for task run:

# persist a generic command execution
v run ./cmd/vshx task run shell.exec -- echo hello

# persist a structured git inspection
v run ./cmd/vshx task run git.readonly --op status --cwd ..

# inspect the saved record later
v run ./cmd/vshx task show <task_id>
v run ./cmd/vshx task logs <task_id>

Inspect MCP bridge shape:

v run ./cmd/vshx mcp inspect
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"demo","version":"0.1.0"},"capabilities":{}}}' | v run ./cmd/vshx mcp serve

Use mcp when you want a stdio host for MCP clients, not when you just want to call tools locally.

Repo layout

• cmd/vshx/ CLI entrypoints
• core/runtime/ tool registry, shell execution, renderers, task store
• core/mcp/ stdio MCP server
• core/config/ shared argument helpers
• modules/ legacy skeleton modules kept for now
• docs/ product direction and runtime notes
• .vshx/ local task artifacts (gitignored)

Key design doc:

• docs/AI_NATIVE_PLAN.md
• docs/RUNTIME_CONTRACT.md
• docs/TOOL_CATALOG.md

Status

Current MVP is focused on the local CLI runtime path:

• run --format markdown|ndjson
• run --stream
• default risk policy with --allow-risky override
• tool list|describe|call
• task run|show|logs
• file-backed task records under .vshx/tasks/
• mcp inspect|serve

Current built-in tools:

• rg.search for ripgrep-backed code and text search
• git.readonly for constrained read-only Git operations
• shell.exec for local command execution
• data.agg as a simple built-in example tool

Current git.readonly behavior:

• supports status, diff, log, and show
• keeps Git access on explicit read-only subcommands
• enriches output with Git-specific fields such as branch state, change counts, commit ids, and entry counts
• renders a markdown-first summary view for the human vshx git ... entrypoint
• keeps raw Git transcript optional in the human CLI through --transcript
• exposes grouped status paths such as staged_paths, unstaged_paths, untracked_paths, and deleted_paths
• exposes compact status summaries for agents through status_entries and status_entries_json
• exposes diff summaries without patch bodies, including file_count, insertions, deletions, changed_paths, created_paths, deleted_paths, renamed_paths, diff_entries, and diff_entries_json
• exposes show metadata such as author, date, subject, and stat-derived changed_paths
• exposes compact log entry summaries through entries, entry_commits, and entry_subjects
• works through CLI, task runtime, and MCP with the same schema

Preferred git.readonly machine fields:

• status_entries_json for git status
• diff_entries_json for git diff
• entries for git log
• changed_paths plus commit metadata for git show

Current rg.search behavior:

• provides a ripgrep-backed search tool with a narrower contract than raw shell usage
• supports query, cwd, path, glob, case, limit, and word
• renders a markdown-first grouped match view for the human vshx rg ... entrypoint
• emits match events in NDJSON and exposes a flattened result event before final
• normalizes ripgrep no-match exits into a successful zero-match tool result
• exposes summary fields such as match_count, displayed_match_count, file_count, matched_files, matches, and truncated

Preferred rg.search machine fields:

• match_count
• file_count
• matched_files
• matches
• truncated

Current output rendering behavior:

• Markdown favors a human-readable summary first, then grouped sections or terminal-style output
• vshx git ... hides raw Git transcript by default and exposes it with --transcript
• NDJSON emits typed events and includes a flattened result event before the terminal final summary

Current contract docs:

• docs/AI_NATIVE_PLAN.md explains the product direction
• docs/RUNTIME_CONTRACT.md defines the current MVP event, result, and tool field contract
• docs/TOOL_CATALOG.md describes the current built-in tool surface and intended usage

Current shell policy behavior:

• allows read-oriented commands such as git status
• blocks obviously risky command shapes such as sh -lc ... by default
• records policy decision and effective risk level in task output
• lets operators override with --allow-risky

Current mcp serve behavior:

• reuses the same runtime contract as CLI and task execution
• tracks initialize and notifications/initialized
• rejects tool methods until the session is ready
• exposes the registry through tools/list
• runs registry-backed tools through tools/call
• exposes placeholder resources/list and prompts/list surfaces

Build helper:

• build.v compiles ./cmd/vshx to bin/vshx
• v run build.v release builds with -prod
• v run build.v clean removes the built binary
• make build|debug|release|run|clean wraps the same workflow
• make mcp-inspect|tool-list|tool-describe|task-demo|smoke gives quick dev/demo entrypoints