Venira
Venira is a workspace-scoped MCP server that gives a coding agent guarded file, shell, git, code-intelligence and diagnostics tools — all sandboxed to the workspace and audit-logged.
Read & search —
list_files,read_file(line ranges/hashes),get_file_info,search(name/content/regex/symbol/weighted queries),recent_files, andread_batch(up to 8 reads in one call).Edit files —
write_file,edit_file(exact-text with stale-hash guard and mismatch diagnosis),edit_batch(all-or-nothing with rollback),apply_patch(unified diff, dry-run), pluscreate,move_path,copy_path,delete_path.Run commands —
shell_run(foreground/background, approval-gated by policy), withshell_status,shell_cancel,shell_cancel_sessionfor polling and killing runs.Checkpoints —
snapshotcreate/list/restore/delete/mirror for git-free rollback before risky changes.Code intelligence —
outline_symbol,diff_files,symbol_references,dependency_graph(TS/JS/Py/Rust/Go/Java/Kotlin),change_impact("what breaks if I edit this?").Local git —
git_status,git_diff,git_log/blame,git_branch,git_commit,git_stash(no push).Secrets & GitHub — encrypted-at-rest
secretstore (set/get/list/delete, inject viasecret_env) andgithub_connectdevice flow.Diagnostics & audit —
health(posture, caches, queue, latency),read_audit(hash-chained log),trace_status,cache_clear.Session helpers —
memory(workspace handoff note) andswitch_workspace(re-root the server).
Provides tools for interacting with GitHub pull requests, including creating pull requests, commenting on them, and merging them through the GitHub REST API.
Provides tools for interacting with GitHub Actions, including checking CI status, triggering workflows, and retrieving CI logs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Venira search src/ for getConfig and show me the matching lines"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
venira-mcp
Fast, workspace-scoped MCP server for coding agents (OpenCode, Claude Desktop, any MCP client).
Three tool modes — Core (23 tools: shell, execute_js, read/search/list, edit/create/move, snapshot, git, memory — for small models) · Default (39 coding tools + shell, no CI/CD) · Expert (52 tools: default + CI/CD). VENIRA_JS_EXEC_MODE=off hides execute_js in every mode (52 → 51, 39 → 38, 23 → 22); otherwise it is registered and approval-gated. VENIRA_SETUP_TOOLS=1 adds the two setup tools detect_harnesses and install_self (+2); npx venira-mcp --install and --print-config do the same from a terminal.
Pure Node, 1 native dependency (better-sqlite3), no GUI, no external binary.
Security scope. Venira is a guard rail with an audit trail, not a sandbox. It runs with the privileges of the OS user that started it. The workspace lock limits the paths the file tools can touch (unless
VENIRA_UNRESTRICTED=1), not what a shell command does: commands are classified by rules (allow / ask / deny) and every call is audited, but a malicious prompt can still steer the agent into running a harmful command that the active profile lets through (withoff, every command runs). Anything running as the same OS user can read the keys inVENIRA_DATA_DIR. For untrusted workspaces, or whenever you need a real isolation boundary, run Venira in a container or VM. Details:SECURITY.md.
1. Setup
One-line install (run in your project, then restart the client):
npx --yes venira-mcp@latest --install auto --workspace .Prefer your agent? Paste this prompt into OpenCode/Claude/Cursor:
Set up Venira MCP for this workspace.
1. Detect my MCP client config path.
2. Run: npx --yes venira-mcp@latest --install auto --workspace .
3. Restart the client. Then call health to verify.Manual config (pick your client):
Client | Config path | Format |
VS Code |
| JSONC |
OpenCode |
| JSONC |
Claude Desktop |
| JSON |
Cursor |
| JSON |
Codex |
| TOML |
All use the same npx command. See §2 for ready-to-copy JSON/TOML.
In this repo .vscode/mcp.json is git-ignored because it holds machine-specific settings (and may relax security flags). Copy .vscode/mcp.example.json to .vscode/mcp.json and adjust it locally.
Related MCP server: MCP ToolHub
2. Client configs (copy-paste)
The examples use two environment variables: the workspace and the tool set. Everything else has a safe default, so you only add a VENIRA_* variable when you want to change that default (see Config recipes).
OpenCode / VS Code / Cursor / Claude / Kimi / DeepSeek / Antigravity — use the wrapper format supported by your client:
// OpenCode: "mcp" > "venira" > "environment"
{
"mcp": {
"venira": {
"type": "local",
"command": ["npx", "--yes", "--package=venira-mcp@latest", "venira-mcp"],
"enabled": true,
"environment": {
"VENIRA_WORKSPACE": "/absolute/path/to/project",
"VENIRA_TOOL_MODE": "expert",
// Small model / restricted context? Uncomment to slim tools/list:
// "VENIRA_TOOL_MODE": "core"
}
}
}
}
// VS Code: "servers" > "venira" > "env"; ${workspaceFolder} expands automatically.
{
"servers": {
"venira": {
"type": "stdio",
"command": "npx",
"args": ["--yes", "--package=venira-mcp@latest", "venira-mcp"],
"env": {
"VENIRA_WORKSPACE": "${workspaceFolder}",
"VENIRA_TOOL_MODE": "expert"
}
}
}
}
// Claude / Cursor and compatible clients: "mcpServers" > "venira" > "env"
{
"mcpServers": {
"venira": {
"command": "npx",
"args": ["--yes", "--package=venira-mcp@latest", "venira-mcp"],
"env": {
"VENIRA_WORKSPACE": "/absolute/path/to/project",
"VENIRA_TOOL_MODE": "expert"
}
}
}
}Generic MCP JSON example
For clients that accept the common mcpServers JSON shape, use the example for the user's operating system as a realistic starting point. Replace the example paths with paths on the user's machine; VENIRA_DATA_DIR is optional and can point to any writable directory. Keep this file private if it contains local paths or credentials.
Windows:
{
"mcpServers": {
"venira": {
"command": "npx",
"args": ["--yes", "--package=venira-mcp@latest", "venira-mcp"],
"env": {
"VENIRA_WORKSPACE": "C:\\Users\\YourName\\Projects\\my-app",
"VENIRA_DATA_DIR": "C:\\Users\\YourName\\AppData\\Local\\venira",
"VENIRA_TOOL_MODE": "expert"
}
}
}
}Linux:
{
"mcpServers": {
"venira": {
"command": "npx",
"args": ["--yes", "--package=venira-mcp@latest", "venira-mcp"],
"env": {
"VENIRA_WORKSPACE": "/home/yourname/projects/my-app",
"VENIRA_DATA_DIR": "/home/yourname/.local/share/venira-mcp",
"VENIRA_TOOL_MODE": "expert"
}
}
}
}mcpServers is a common client configuration shape, but some clients use a different outer key or file format. Preserve the Venira command, args, and environment values when adapting the example. The approval command returned at runtime uses the effective data directory from this configuration, so users and agents should copy data.approval.approve_command instead of constructing a path themselves.
Codex (~/.codex/config.toml):
[mcp_servers.venira]
command = "npx"
args = ["--yes", "--package=venira-mcp@latest", "venira-mcp"]
[mcp_servers.venira.env]
VENIRA_WORKSPACE = "C:\\path\\to\\project"
VENIRA_TOOL_MODE = "expert"Config recipes
Pick one block and put its variables in the env section of your client config. Every other variable keeps its default.
Recipe | Variables |
Minimal (recommended) |
|
Fewer prompts on a personal machine | Minimal, plus |
Full trust (isolated or personal machine only) | Minimal, plus |
off keeps full trust: shell checks off (hard-deny included), no workspace lock (VENIRA_UNRESTRICTED=1), VENIRA_JS_EXEC_MODE=auto as the default JS mode, no elicitation, full env passed to shell, reveal=true prints secrets and nothing prompts. A variable you set yourself always wins over the profile (e.g. VENIRA_JS_EXEC_MODE=off stays off). Deliberate opt-ins are never implied: VENIRA_SHELL_OVERRIDES, VENIRA_ALLOW_SELF_INSTALL and VENIRA_SECRET_KEYCHAIN.
Do not write a variable just to restate its default (for example VENIRA_OUTPUT_MODE=full, VENIRA_USE_RIPGREP=1 or VENIRA_SECURITY_PROFILE=balanced).
Security profiles
| Shell policy | Use |
|
| Read-only and workspace-local allowlist runs without approval |
|
| Recommended general-purpose setting |
|
| Ask-rule and unclassified commands run; hard-deny commands require approval |
|
| Full trust: shell checks off, no workspace lock, JS exec |
VENIRA_SHELL_MODE is an advanced override and takes precedence over the profile. VENIRA_JS_EXEC_MODE separately gates the JavaScript tool: off (default) hides it, ask registers it with per-call human approval (skipped when VENIRA_PERMISSION_MODE=allow_all), semi-auto registers it without approval but keeps the containment (workspace-only fs, scrubbed env, no child processes; network is always open), auto registers it without approval and without any containment (full fs access, inherited env; personal machines only). switch_workspace follows the profile the same way: trusted/off (and an explicit VENIRA_UNRESTRICTED=1) switch to any existing directory; strict/balanced switch only inside VENIRA_WORKSPACE_ROOTS, which unset locks switching to the spawn workspace.
Choose
trustedwhen you want fewer prompts on a personal machine. Chooseoffonly when you intentionally accept that shell checks are disabled; JS exec is still gated byVENIRA_JS_EXEC_MODE(a human gate forexecute_jsonly counts when that mode isaskandVENIRA_PERMISSION_MODEis notallow_all). Thesecret_envgate remains active in every profile. Elicitation hangs off the shell mode:strictnever prompts (CLI grant only),balancedprompts for every unclassified ask-rule command,permissivenever prompts at all (only thecommand_substitutionalways-ask rule, hard-deny commands downgraded toask.deny.*, andsecret_envstill prompt),offnever prompts.
Advanced configuration
Variable | Default | Change when |
| Profile mapping | You need to override only the shell policy ( |
|
|
|
|
| Keep workspace path restrictions enabled; do not set to |
See the full environment reference in §6 for caching, shell, provider, and diagnostic options.
3. Benchmark (per-op, p50)
Measured: Windows + Node 24, standalone build, 2026-11-01.
Op | p50 | Notes |
Cached | 8.0 ms | warm cache |
| 12.8 ms | one call, 8 items |
| 6.2 ms | cached |
| 11.5 ms | p95 ≈ 1.3 s (file count dependent) |
| 28.5 ms | |
| ~930 ms | 2 s wait budget dominates |
First call | 113.7 ms | post warm-up |
Batch: 8 reads as one batch call (16.6 ms) vs 8× individual (~76 ms) — the round-trip saving that makes the agent loop fast.
Agent tool-path benchmark: Venira MCP vs Codex exec_command
Measured on 2026-11-07 on one Windows 11 build 26200 machine (Intel Core i5-1035G1,
8 logical processors, 11.8 GiB RAM, Node v24.20.0). Each workload used 20 paired
samples per phase, alternating call order. Venira used the persistent MCP connection;
each native exec_command call launched a fresh PowerShell process. Cache-miss samples
cleared Venira's in-process cache; warm samples reused it. The OS filesystem cache stayed
warm.
Workload | Phase | Venira p50 / p95 |
| Ratio of p50s |
Read first lines of 8 files in one batch | Cache miss | 53.5 / 72 ms | 962 / 1,121 ms | 17.98× |
Read first lines of 8 files in one batch | Warm | 39 / 60 ms | 1,103.5 / 1,549 ms | 28.29× |
Search | Cache miss | 118.5 / 188 ms | 1,034.5 / 1,507 ms | 8.73× |
Search | Warm | 34.5 / 152 ms | 1,018 / 1,383 ms | 29.51× |
Both workloads matched exactly in all 20 pairs: normalized text for the 8-file batch and sorted file/line locations for search. These are practical agent tool-path timings, not raw filesystem timings. A separate 100-sample component benchmark shows native PowerShell can be faster for simple uncached reads; the largest Venira gains are on warm list/search and avoiding a fresh shell process. The p95 estimates are rough with 20 samples, and results from this one machine are not a general performance guarantee.
See the full methodology and results and
raw samples. Reproduce the component benchmark from the
repository root with npm run bench:tools -- --runs=100.
4. Three tool modes
Three tool modes set which tools the client sees. Set via VENIRA_TOOL_MODE env var or
"toolMode" in venira.config.json (env wins). VENIRA_DISABLE_TOOLS hides additional tools on top.
core is the small-model / restricted-context preset (the old VENIRA_PROFILE=core, now folded into this one variable). Unlike the other two modes it is an allowlist: only the must-have tools below are advertised, and any tool added later stays out of tools/list until it is added to CORE_TOOLS (tools/project-tool-mode.ts), because every extra schema costs tokens on every prompt.
Mode | Tools | Includes |
| 23 | Allowlist: |
| 39 | Read/write/edit/search, code intel, snapshots, shell, |
| 52 | Everything in default + |
delete_path is always available. In balanced / strict mode, shell rm -rf / / ~ and Windows drive-wide deletes are hard-denied, and recursive/force deletes (Remove-Item -Recurse -Force, rd /s /q, del /f /q) need approval. permissive mode lets ordinary ask-rule and unclassified commands run without a prompt, but hard-denies require approval and uninspectable command substitutions require approval in every policy-enabled mode.
5. Tools quick reference
All tools return the standard envelope (ok, kind, data, hint, elapsed_ms).
Read (batch-safe, cached)
Tool | Purpose |
| List files/dirs, depth 1–3, limit ≤ 200 |
| Read a file by line range; optional |
| File/dir metadata (kind, size, mtime); |
| Search by file/dir name, content, regex, or symbol; |
| Recently modified files (index-first, scan-fallback) |
| Up to 8 read-only ops in one call; each item takes the same arguments as its standalone tool ( |
| Diagnostics: capability, queue, cache hit-rates, p50/p95, security limits notice, and |
| Re-root the workspace to another directory mid-session — for clients that spawn the server once (e.g. Claude Desktop). Follows |
| Read recent audit log rows |
| One handoff note per workspace that outlives the chat: |
Whole-file hashes. read_file returns sha256 = the hash of the whole file (sha256_scope: "file"), even when the call returned only a slice, and text_sha256 = the hash of the text that was returned. sha256 is therefore safe to send back as expected_sha256; text_sha256 is not. The hash covers the raw bytes, so a file with a BOM round-trips. When a write or edit refuses a stale hash (stale_content), the file is left untouched and the response asks for a fresh read: re-read the file, rebuild the patch against the current content and send the new hash - never replay the same edit unchanged. In compact mode the text arrives as preview (preview_truncated marks a cut); the hash fields are always there.
Recovery that fits the tool. A failure names the call that can recover from it: a missing secret points at secret action=list, a missing device flow at github_connect action=start, a missing checkpoint at snapshot action=list, a missing file at the file tree. A read batch that lost one item is marked partial: true and reports failed_count and succeeded_count, so the successful reads stay visible. health in compact mode keeps whole sections and names the ones it dropped, and sections asks for exactly the parts you need.
A failed edit answers with a diagnosis, not a dump. When old_text is not in the file, the error says where it went wrong and how small the gap is: mismatch carries the file, the line, the first differing character, how many characters the line is off, and the two lines it compared. context carries three lines before and three after the wrong spot - without line numbers, so it can be copied straight into old_text (numbered has the numbers for orientation). The payload stays under a kilobyte even for a long edit, and the file is never changed by a refused edit. indentation and line_endings say whether the file uses tabs or spaces and CRLF or LF - the two things plain text cannot show.
Snippets that run. execute_js gives a snippet with a top-level await the same require it has in CommonJS mode, so the two are not mutually exclusive. A static import of a network module is refused before the snippet runs (in the contained modes) with the way out; a require of one is blocked at runtime, so a snippet that proves the block still runs. A top-level return, a timeout and a failed snippet all come back with a reason you can act on, and the envelope carries command_status: "failed".
Write (mutating, pass reason)
Tool | Purpose |
| Create/overwrite/append; |
| Replace |
| Multiple edits; stops at first failure and attempts checkpoint rollback. Check |
| Create a directory (missing parents are created; use |
| Move or rename a file/dir; |
| Copy a file, or a directory with |
| Apply a unified diff (create/modify/delete/rename), all-or-nothing; |
| Delete file/dir; not undoable |
Checkpoints (git-free rollback)
snapshot — create/list/restore/delete. Content-addressed, deduplicated, atomic per-file restore. The id carries the local timestamp (snap-20261113-001500-3f9ac2); the exact instant is created_at_ms (epoch milliseconds).
Code intelligence
Tool | Purpose |
| Parse a file's symbols (functions, classes, types) with line numbers |
| Unified diff between two files |
| Find all occurrences of a named symbol |
| TS/JS/Python/Rust/Go/Java/Kotlin import/symbol graph (JSON/DOT/Mermaid) |
| "What breaks if I edit this?" — bounded reverse/forward closure |
Two caps, two names. symbol_references has max_references (how many references come back - the token bill, default 100) and limit (how many workspace hits are scanned - the work, default: max_references). The result says which one bit: count (found), returned, omitted, scan_limit and limited.
change_impact says what it could not resolve. unresolved[] holds the seeds that did not resolve (the symbol is not declared, or the name is ambiguous in N files) with a next_step; the graph-wide unresolved imports are only counted (stats.unresolved_imports), because they say nothing about the seeds and cost tokens on every call.
The graph's side lists are short and counted. dependency_graph returns the 50 most used external[] entries and the 10 first unresolved[] ones; stats.externals and stats.unresolved_imports hold the full counts, and limited: true says that a list was cut.
Shell (async, policy-gated)
Tool | Purpose |
| Run a command; |
| Poll a running command (not queued, not audit-logged) |
| Kill a running command by |
| Kill all shell runs in this session |
Repeated-failure guard. A shell invocation is fingerprinted (normalized command, shell, resolved cwd and the non-secret inputs; secret_env contributes its names only) and the fingerprint is remembered per session when the run fails or times out. The identical invocation is then not run again: the call fails with repeated_failure and carries data.previous (exit code, timed-out flag, bounded stderr tail, failure count). Nothing is stored but the hash - never the command text, never a secret value - so a repeat with secrets is reported as "same command and inputs", never as an exact match of the secret values. Change the command, the shell, the cwd or the inputs and it runs normally; a deliberate rerun of the identical command is retry_failed: true. A successful run clears the memory.
What the shell really did. The response names the binary that ran the command (shell_path, shell_kind: native, wsl, git-bash or unknown) - on Windows bash is often the WSL launcher, which runs the command inside a Linux distro and reports its own messages in UTF-16 (those are decoded for you, and a WSL without a distribution comes back with a shell_hint). cmd.exe receives the command verbatim, so double quotes survive; PowerShell reports the native exit code of the last command (git status outside a repository reports 128, not 1), while a failing cmdlet still reports 1.
Choosing a shell on Windows. powershell starts powershell.exe (5.1), which has no && / || pipeline-chain operators; pwsh starts PowerShell 7+ (winget install --id Microsoft.PowerShell), which has them. pwsh must be on the PATH of the server process, so restart the MCP client after installing it. Policy treats both as the same PowerShell dialect: every segment of an && / || chain is classified on its own, so a denied command after && is still denied (policy_adv_dialect_pwsh_chain_operators). pwsh starts slower than cmd; set VENIRA_DEFAULT_SHELL=pwsh only if you want it for every call. A shell binary that is not installed fails with [shell_unavailable] and an install hint instead of returning exit code -1. In PowerShell an unquoted (...), @(...) or {...} counts as a substitution the policy cannot inspect, so a command that carries one always asks for approval in policy-enabled modes, including permissive: PowerShell evaluates the group before the command runs, so git status (Remove-Item -Recurse -Force $HOME) would otherwise delete while looking like read-only git (policy_adv_dialect_powershell_grouping_expressions).
Local git (this repo)
Tool | Purpose |
| Parsed worktree status: branch/detached, upstream (+ |
| Parsed diff ( |
| Commit list ( |
|
|
| Commit staged changes, or stage |
| `action=push |
Read-only git (status, diff, log/blame, branch list/current, stash list/show) needs no reason; mutating calls do. Mutations invalidate the whole cache (worktree-wide change). Local only against the workspace repository root (git rev-parse --show-toplevel; paths stay workspace-relative); push is never performed by these tools — routine git pushes need no approval, force/delete/URL pushes ask one, and ALLOW_ENV_READ is the only remaining named override.
Git provider: PR/CI (GitHub, GitLab, Bitbucket)
pr_create/comment/merge/list/close/reopen, ci_status/trigger/logs/wait, ci_control (cancel / retry-failed; Bitbucket supports cancel only) — same tool args across providers; token from secret or env vars.
CI reads are bounded and never hide a cap:
Pagination — status/job/check-run/step lists follow the provider's next-page link (
Linkheader on GitHub/GitLab, bodynexton Bitbucket) for at most 5 pages / 200 items, stay on the configured API origin, and never fetch the same page twice. When a cap or the provider total stops the walk, the result says so (truncated/partial) instead of reporting a partial list as complete.Verdicts — a finished Bitbucket pipeline/step is read from
state.result(not justCOMPLETED), so a failed run is never shown green.Logs — failing steps/jobs are read first; archives and entries are byte-capped (see
VENIRA_GIT_LOG_*), and a log whose declared size is over the cap is refused before it is downloaded.ci_wait— one bounded long-poll (no polling loop). Returnssummary(one line),next_step(wait_again·merge_or_continue·fix_failing_step_then_push·read_logs·inspect_status),failing_jobs(max 5) and, on failure, afailure_tailof the first failing job (numeric ids on GitHub/GitLab, UUID step ids on Bitbucket).
Secrets (encrypted at rest)
secret — store/inspect/remove credentials by name; AES-256-GCM; rotation metadata; expired secrets refused.
github_connect — GitHub Device Flow, tokens in vault.
Diagnostics & planning
explain_error — turn an error into a cause + next tool calls (rule table, no model).
plan_read_batch — plan which files to read for a task, returns ready read_batch call.
cache_clear — clear the in-process caches (all / read / info / list / search / recent / negative / graph / shell) when reads look stale because a tool changed files outside Venira.
trace_status — show recent traced tool calls and the trace configuration; tracing is always on (VENIRA_TRACE was removed), and VENIRA_TRACE_FILE additionally appends to a rotating file.
JS execution
execute_js — run synchronous JS (opt-in via VENIRA_JS_EXEC_MODE). The mode decides both the approval step and how much the snippet is contained:
Mode | Approval per call | Network | Filesystem | Environment |
| tool not registered | n/a | n/a | n/a |
| yes (skipped when | open (every mode) | workspace only | scrubbed |
| no | open (every mode) | workspace only | scrubbed |
| no | open | unrestricted | inherited |
Contained (
ask,semi-auto): Node's permission model limits reads and writes to the workspace and denies child processes and workers; onlyPATH,TERMandNODE_PATHare passed (HOMEandUSERPROFILEare empty). Network access is open in every mode. This is best-effort containment, not a sandbox.autodrops all of the above: the snippet has the full network, the full filesystem, child processes and the server's environment (including any tokens in it). Use it only on a personal machine you trust.healthreportsjs.exec_without_approval(a warning) for bothsemi-autoandauto; it does not distinguish the two.semi-autois the old behaviour ofauto. If your config saysVENIRA_JS_EXEC_MODE=autoand you want the snippet to stay contained, change it tosemi-auto.Output is still redacted for obvious secret assignments, and the timeout (default 30 s, max 10 min) applies in every mode.
6. Environment variables (key ones)
Full reference: the source reads 80+ distinct supported VENIRA_* names; this table lists the documented ones. See the source or npx venira-mcp --help for the rest.
Variable | Default | What it does |
|
| Workspace root; all paths resolve against it |
|
|
|
|
|
|
|
| What |
|
|
|
|
| Selects the shell policy: |
| Profile mapping | Advanced override for shell policy: |
|
| Shell used when a call does not name one: |
|
| Characters kept in a shell run's stdout/stderr tail (minimum |
|
| Per-stream cap (stdout and stderr each) that a shell run records |
|
| Upper bound for a caller-supplied shell timeout ( |
|
|
|
|
|
|
|
| Max files collected by the JS fallback walker before it stops and reports |
|
|
|
|
|
|
| per-user OS path | Where audit DB + encrypted secrets live |
|
| Shared checkpoint root for every project and client; each workspace gets its own sub-folder (absolute path) |
| unset | Exact checkpoint store for a single project, no sub-folders; wins over |
|
| Checkpoints kept per project (oldest pruned on create) |
| unset | Optional append-only copy of the checkpoint store in this existing folder (OneDrive/Dropbox, NAS share, USB drive, rclone mount); absolute path, must be outside the store and the workspace |
|
| Time budget of one mirror run; it stops between files ( |
| unset | Comma-separated tool names to hide from |
| inferred |
|
| unset | Fallback token when no provider-specific secret found |
|
| Per-request timeout for provider JSON calls (1 000–600 000) |
|
| Retries for safe GET reads only (0–3); POSTs are never replayed |
|
| Timeout for CI log downloads (1 000–900 000) |
|
| Max bytes of a CI log archive; larger declared sizes are refused before download |
|
| Per-entry and total decoded log text caps |
| unset | Operator allowlist: |
|
| Permission mode passed when the session scope opens ( |
| auto | Set for test/verify runs to separate audit rows |
| built-in: | Extra ask-rule ids (comma-separated) that may be approved with |
|
| Lifetime of an in-memory |
|
|
|
|
|
|
| unset | Path to a JSON shell policy file (allow/ask/deny rules); never read from the workspace automatically |
| unset | Per-tool policy rules, inline JSON or a file (see |
Advanced tuning knobs (all optional)
Sensible defaults; leave any of these unset unless you know why you set them.
Variable | Default | What it does |
|
| Pretty-print JSON envelopes |
|
| Per-item response budget inside |
| unset | Extra environment variable names passed through to shell runs, beyond the scrubbed baseline |
|
| Cache read-only shell results |
|
| Compatibility flag (shell output caching is always read-only — nothing mutating is ever cached) |
| unset | Explicit path of the JSON config file (git provider settings); never auto-read from a workspace |
| unset | Allowlist of roots |
| unset | Enable only the directory-listing cache |
| unset | Enable only the search cache |
|
| Directory-listing cache lifetime |
|
| Lifetime of cached not-found results |
|
|
|
|
| Search cache lifetime |
|
| Size cap of each list / search / recent / references cache |
|
| Files modified this recently are re-read instead of served from the read cache ( |
|
| Total size cap of the file-read cache |
|
|
|
|
| Audit rows older than this many days are pruned |
|
| Total size cap of a project checkpoint |
|
| Largest single file a checkpoint captures |
|
| File-count cap of a checkpoint ( |
| built-in | Largest provider API response accepted |
| built-in | Total CI log bytes returned per call |
| built-in | Redirects followed (same-origin only) |
|
| Allow plain-HTTP provider URLs (tokens may travel in clear text) |
|
| Deprecated alias of |
| unset | Extra API hosts the provider client may call |
| unset | Provider API base URL (self-hosted instances) |
| unset | Deprecated alias of |
| unset | HTTP(S) proxy for provider calls |
| unset | Repository slug override ( |
| unset | GitHub repository slug override |
| unset | GitLab project path override |
| unset | Bitbucket repository slug override |
| unset | Name of the stored secret holding the provider token (default |
| unset | Name of another environment variable holding the provider token (e.g. |
| unset | Username for providers that need one (Bitbucket app passwords) |
| unset | GitHub token (falls back to |
| unset | GitLab token (falls back to |
| unset | Bitbucket token (falls back to |
|
| Windows keychain for the secret store key ( |
| unset | Also append the trace to this file (rotates at 10 MB) |
7. Security model
Conservative by default:
Workspace lock: all paths validated inside
VENIRA_WORKSPACE;../escape rejected (path_escape).Security profile (
VENIRA_SECURITY_PROFILE, defaultbalanced): sets the shell policy.VENIRA_SHELL_MODEcan override it. Everyshell_runcommand is classifiedallow,askordeny.balanced(default): hard-deny rules refuse the command; ask rules need approval; routine dev-workspace commands run; anything unclassified needs approval.strict: likebalanced, but only a read-only / workspace-local allowlist runs without approval.permissive(thetrustedprofile): ordinary ask-rule and unclassified commands run without a prompt; hard-deny matches become approval requests (ask.deny.<rule>), and uninspectable command substitutions always require approval.off: the shell policy is disabled — every command runs, nothing is asked or denied (onlysecret_envinjection still asks). Prints a startup warning; use only in a trusted environment. Previouspermissivebehaviour (v1.14.4) =off.Hard-deny (14 rules): disk destroy, filesystem mount/overwrite, shutdown/reboot, fork bomb, pipe download to shell, privilege escalation (sudo/doas/runas), filesystem root/drive-home delete (
rm -rf /,rm -rf C:\,Remove-Item -Recurse -Force $HOME, …),chmod 777 /, Windows drive-wide and wildcard mass delete, encoded PowerShell commands, self-approval (touching the approve CLI or approval store), protected credential/key files.Ask (20 rules): command substitution, reads/writes/
cdoutside the workspace, network access, package mutation, git history rewrite, container/VM control and state, process control andtaskkill /f, secret dumps, dynamic execution and wrapper commands,find -delete/-exec, destructive recursive/force deletes (Remove-Item -Recurse -Force,rd /s /q,del /f /q; preferdelete_path), attribute reset, infinite writes to NUL, unresolved file arguments.Deny always wins over ask.
Secrets: AES-256-GCM encrypted at rest; values never in tool metadata;
secret_envrequires human approval; expired secrets refused.Provider DLP: Secretlint scans PR/CI request args and HTTP payloads; detected credentials blocked before sending, withheld from response.
Audit trail: all ops (including failures) written to SQLite WAL;
read_auditfor post-mortems.Token transport: provider token in
Authorizationheader only; dropped on cross-origin redirect.
Approvals — what needs a human, and how it is granted
Gate | Triggers when | Switch (default) |
Shell | A hard-deny rule matches: refused outright, no approval possible |
|
Shell | An ask rule matches, or the command is unclassified in |
|
Secret injection |
| always asks, in every mode |
| Every call |
|
Secret plaintext |
|
|
Self-install |
|
|
Named shell override |
|
|
Routine git (status, diff, log, add, commit, rm, push fast-forward with publish flags, pull, fetch, clone, merge, rebase, cherry-pick, revert, tag, branch, reset without --hard/--keep, checkout, switch, stash) runs in balanced without an approval; force/delete/URL pushes and the other git history rewrites (reset --hard, clean -fd, branch -D, filter-branch, reflog) stay in git_history_rewrite and still need one. The removed ALLOW_GIT_PUSH override no longer exists; setting it fails closed with [config_invalid] VENIRA_SHELL_OVERRIDES accepts only: ALLOW_ENV_READ. ALLOW_ENV_READ covers exactly one plain .env file in the workspace (no globs, no redirects, no substitutes); overrides require a reason and win for exactly one call.
Granting a shell or JS approval:
The call fails with
[approval_required]and returnsdata.approval_id(valid for 5 minutes) together with the command or code, the rule and the reason. Shell and JS share one payload,data.approval:{ approval_id, gate, rule, reason, subject_preview, expires_at, approve_command, retry_with: { tool, arguments } }.A person copies
data.approval.approve_commandexactly into an interactive PowerShell terminal (the returned command includes the server data directory and works in Windows PowerShell and PowerShell 7), reviews the request and answersy. The CLI refuses without a TTY.--yesskips the prompt.--sessionextends the grant to the same command group until it expires, but only for rules inVENIRA_SESSION_GRANT_RULES(built-in:cd_outside_workspace). The command runs the installed build (node <install>/bin/venira-mcp.js ...), so the human approves the same version the agent is talking to; it never downloads a package from the registry.The agent retries the same call with
approval_id. The grant is HMAC-signed, tied to the session, bound to the exact command / shell / cwd /secret_env/ rule (or code / argv for JS), and single-use. Concurrent retries of the same id cannot both run: consumption is an atomic file claim, so exactly one wins.
TTL behavior: the pending request (approval_id) is valid for a fixed 5 minutes and cannot be revived by retrying. A --session grant lasts 10 minutes by default (VENIRA_SHELL_APPROVAL_TTL_MS) and lives only in this server process; restarting the server clears it.
Agent helpers:
shell_runwithdry_run: truereturns the tier, rule andwould_run/requires_approvalwithout running anything or creating an approval, so an agent knows beforehand which command will be asked.approval_wait_s(max 45) onshell_run/execute_jskeeps the call open while the human approves; a grant that arrives in time runs the command in the same call, otherwise you get the normal[approval_required](the pendingapproval_idstays valid). Keep it below the client's request timeout.healthreportsapprovals(mode, JS gate, elicitation, session rules, TTL, max wait), the sharedposturereport (level, stable finding ids such asworkspace.unrestricted,profile.off,combo.unrestricted_open_shell,js.exec_without_approval) and the flatwarningslist. Posture findings are warnings only; invalid values already fail closed at startup.doctorsurfaces the same report.
Alternative (in balanced mode, shell_run only): ask-rule commands the policy cannot statically clear prompt through a confirmation dialog in MCP clients that support elicitation, and accepting it records the grant for you. In permissive the prompt is reserved for the always-ask command_substitution, hard-deny commands (which arrive as ask.deny.*) and secret_env; ordinary ask-rule commands run without a prompt. strict never prompts; off never prompts.
Removed in v1.15: approval_token and VENIRA_SHELL_AUTO_APPROVE_TOKEN. Passing approval_token now returns [approval_invalid] with a hint to use approval_id; setting the env var only logs a warning and is ignored.
Removed: VENIRA_ALLOW_JS_EXEC and VENIRA_JS_EXEC_APPROVAL — use VENIRA_JS_EXEC_MODE (off / ask / semi-auto / auto) instead; VENIRA_SHELL_EXIT_EARLY, VENIRA_SHELL_TIMEOUT_POLICY (always hard), VENIRA_SHELL_ENV_PASS_ALL, VENIRA_SHELL_ELICIT, VENIRA_SECRET_ALLOW_REVEAL, VENIRA_AUDIT_FAST, VENIRA_CACHE_ALL and VENIRA_TRACE (always on) — see CHANGELOG.md (merged into VENIRA_SHELL_MODE/VENIRA_PERMISSION_MODE). Setting an old var only logs a warning and is ignored.
Approvals are a guard rail, not a sandbox: a process running as the same OS user can read the approval key.
Snapshot store (checkpoints)
Checkpoints live outside every workspace, in one shared per-user folder, so every MCP client that opens the same project sees the same history:
%LOCALAPPDATA%\venira\snapshots\ (Linux: ~/.local/share/venira/snapshots, macOS: ~/Library/Application Support/venira/snapshots)
my-app\ project.json index\ blobs\
my-app-6cb89aac\ a second workspace that is also called "my-app"Folder name = workspace folder name. The first workspace to claim a name keeps it (recorded in
project.json); a different workspace with the same name gets a-<hash8>suffix. The same workspace always maps to the same folder, whatever the path casing or 8.3/symlink spelling.Override with
VENIRA_SNAPSHOT_ROOT(shared root) orVENIRA_SNAPSHOT_DIR(exact folder, single project). Both must be absolute paths; a relative one fails with[config_invalid].The file tools (read, write, edit, search, delete) refuse anything under the snapshot root or exact dir, the same way they refuse the data dir. Only
snapshottouches the store.Retention is per project (
VENIRA_SNAPSHOT_KEEP), so one busy project cannot push out another's checkpoints.Shell commands are guarded too: any read, write or delete operand inside the snapshot store is a hard deny in
balanced/strict(deny.protected_file_access) and needs approval inpermissive.offdisables shell policy entirely, so keep checkpoints you cannot afford to lose in a separate backup as well.Unreadable checkpoints are reported, never dropped silently.
snapshot action=listaddsunreadable[](each row hascodeandmessage:snapshot_version_unsupported= written by a newer venira-mcp,snapshot_unsafe_path= a file path leaves the workspace (written by an older build; it is never restored),snapshot_corrupt= broken index file) and a hint. While any index is unreadable, blob cleanup is paused (gc_skipped: "unreadable_manifests"on delete), because that index still owns blobs this build cannot enumerate. For the first case upgrade venira-mcp; forsnapshot_unsafe_pathandsnapshot_corrupt,snapshot action=deletewith that id removes the index when its header names this workspace (was_unreadable: true) and cleanup resumes; an index whose bytes cannot be parsed at all, or that names another workspace, is refused, so remove such a file yourself (agent shell access to the store is denied by design).Manifests carry a
version. Older layouts are upgraded in memory when read (MIGRATIONSinlib/snapshot-store.ts); the file on disk is never rewritten.
Backing up the store
The store is plain files: immutable content-addressed blobs\<ab>\<sha256>, gzip manifests in index\ written by write-then-rename, and project.json naming the owning workspace. A backup is a folder copy; a restore is copying it back to the same location (a checkpoint only restores into the workspace recorded in its manifest).
Run the copy yourself, outside the agent: shell policy denies the store to agent commands.
Copy the shared root (
VENIRA_SNAPSHOT_ROOT) to cover every project, or one project folder. Windows:robocopy "%LOCALAPPDATA%\venira\snapshots" "D:\backup\venira-snapshots" /E; Linux/macOS:rsync -a ~/.local/share/venira/snapshots/ /mnt/backup/venira-snapshots/(macOS: theApplication Supportpath above).Do it while no agent is creating or deleting checkpoints. If you copy in two passes, take
index\first andblobs\second: a blob is always written before the manifest that references it, so that order cannot capture a manifest without its blobs, while the reverse order can. Blobs without a manifest are harmless leftovers.After restoring a backup,
snapshot action=listshould show the expected count and nounreadableentries.
Mirroring the store (optional)
Set VENIRA_SNAPSHOT_MIRROR_DIR to an existing absolute folder and venira keeps a second copy there, with no cloud SDKs, credentials or network code of its own (point it at a OneDrive/Dropbox folder, NAS share, USB drive or rclone mount and let that tool move the bytes).
Same layout as the store (
<mirror>\<project>\project.json,index\,blobs\), so restoring is copying the folder back to the store location; there is no separate format.After every
snapshot action=createthe result carriesmirror(status,copied_blobs,copied_indexes,bytes,failed[],error). It is best-effort: a mirror problem never changes the checkpoint's own status.snapshot action=mirrorruns the same sync on demand; addverify=trueto re-hash every blob already at the mirror and re-copy bad ones.Order is blobs, then indexes, then
project.json, so the mirror never holds a checkpoint whose blobs are missing. Every copy is verified (blob sha256 equals its file name; index bytes equal the source) before it gets its final name. A corrupt local blob blocks only the checkpoints that use it.Append-only: venira never deletes anything at the mirror. A checkpoint pruned locally (
VENIRA_SNAPSHOT_KEEP) or deleted stays at the mirror until you remove it by hand, so expect it to grow; the only overwrite isverify=truereplacing a file that no longer matches its source.Bounded: a run stops between files once its time budget is spent and reports
partial/timed_out; run it again to resume (only missing files are copied). A first sync of a large store may need a few runs.Refused (
[config_invalid]): a relative path, a folder that does not exist (venira never creates the mirror root, so an unmounted drive is not silently replaced by a local folder), and a folder that equals, contains or sits inside the local store or sits inside the workspace. A mirror folder already owned by a different workspace fails with[mirror_conflict].The mirror folder is a protected root like the store: file tools refuse it and shell commands that read, write or delete inside it are denied.
To restore after losing the store: copy
<mirror>\<project>back to the store location (for example%LOCALAPPDATA%\venira\snapshots\<project>) with venira stopped, thensnapshot action=list. Unreadable local indexes are not mirrored (they are counted inskipped_unreadable).
Threats this does NOT protect against: a malicious prompt can still instruct the agent to run destructive commands. Use a container/VM for untrusted workspaces — see ISOLATION.md for Docker, WSL 2 and Windows Sandbox setups, including mounts, network controls and their limits.
8. Envelopes & error codes
Success:
{ "ok": true, "status": "completed", "kind": "file_read", "data": { … }, "hint": "Next chunk: …", "elapsed_ms": 2.57 }Failure:
{ "ok": false, "status": "failed", "error": { "code": "not_found", "message": "…", "retryable": false }, "hint": "Check with list_files first", "next_actions": [{ "tool": "list_files", "arguments": { "relative_path": "." } }] }ok describes the tool operation. For shell_run, a command that ran and exited non-zero still has ok: true, but the envelope status names the command: completed, failed, running, cancelled (or unknown when the shell never reported an exit code). command_status repeats the same outcome in the shell vocabulary (succeeded / failed / running / cancelled) and hint says what to do next. A read batch with failed items reports top-level ok: false, status: "partial", and error.code: "batch_partial_failure"; inspect data.responses for each result.
Timestamps and ordering. Every timestamp a tool reports is epoch milliseconds and says so in its field name (started_at_ms, completed_at_ms, created_at_ms, timestamp_ms); the only exception is the since_unix filter of read_audit, which takes seconds. Every "recent list" reads newest first: the audit rows, the checkpoints and the trace buffer.
Counts vs. caps. A tool that caps a list says so: count is what was found, returned is what came back, omitted is what the cap cut, and limited: true marks the cut (symbol_references, search, list_files).
In compact mode, shortened payloads set trimmed: true and truncated: true; summary describes omitted content. For an otherwise unsupported large payload, data.preview_text contains a bounded JSON-text preview and summary reports the original size and shape. Large error messages or attached error data are also explicitly marked as trimmed. Use full when the complete payload is required.
Common codes: not_found, invalid_request, old_text_not_found, old_text_ambiguous, stale_content, repeated_failure, command_denied, shell_unavailable, path_escape, resource_limit, sensitive_result, unsupported, internal.
9. Agent instructions (paste into AGENTS.md / CLAUDE.md)
Venira MCP rules:
1. Unfamiliar task: call plan_read_batch first, then run steps[0].
2. Read with read_batch (up to 8 items). Never re-read a file a tool already returned.
3. Prefer edit_file / edit_batch over write_file; pass `reason` on every mutation.
4. Snapshot before multi-file or destructive changes.
5. Short commands: shell_run with background: false. Long jobs: background: true, then poll shell_status.
6. Do not call execute_js unless the user asked for JS; in `ask` mode it needs per-call approval. Network access is always open in every mode; in `semi-auto` the filesystem is limited to the workspace and the environment is scrubbed, in `auto` the containment is dropped.
7. On failure, follow the envelope's hint. Treat ok:false + retryable:false as final.
8. Report only what the tool returned.
9. On [approval_required]: stop, tell the user the approval_id and approve_command, do not loop or approve it yourself; retry once with data.approval.retry_with after they confirm. Use dry_run: true to preview a command's tier.10. Development
npm run build # tsc → dist/ (verify launches dist/server.js, so rebuild before verifying)
npm run smoke # in-process sanity check
npm run doctor # 15 preflight checks
npm run verify # 579 behavioural + security checks
npm run coverage:shell # V8 coverage for lib/shell-*.ts (report only, no thresholds)
npm run bench:mcp # end-to-end numbersAdding a tool:
Register in
tools/project.ts→registerProjectTools, use theconfig(title, meta, annotations)helper (metais onlyspeed_profile+batch_safe), and add the model-facing wording (about / use / avoid / out) toTOOL_DOCSintools/project-docs.ts;test:tool-schemafails for a tool without an entry.Read-only: route through
executeCached; mutations: add toMUTATINGset.Envelope: use
buildEnvelope/errorEnvelopefromlib/output.ts.Add a check in the matching section module under
scripts/verify/(scripts/verify.tsonly orchestrates); update the decision tree inserver.tsINSTRUCTIONS.npm run build && npm run verify && npm run bench:mcp— paste numbers in the PR.
11. Troubleshooting
Symptom | Fix |
| Run |
| Path resolves outside workspace; use a workspace-relative path |
Shell command not finishing |
|
| Unusual platform; run |
SQLite binding unavailable | The server still starts. Audit writes are skipped in the default best-effort mode; set |
| Another process has the WAL locked; make sure only one server writes to the same data dir |
Everything slow |
|
License
Licensed under the GNU Affero General Public License v3.0 (AGPLv3) — see LICENSE.
Free for developers, individual use, and open-source projects. Embedding Venira into proprietary closed-source services or commercial agent platforms requires a commercial license from the author.
Available Tools
38 toolsapply_patchApply patchADestructive
Apply a unified diff (git apply compatible) to one or more files, all-or-nothing. Every file is validated in memory before anything is written; a failing hunk rolls every file back from an automatic checkpoint, like edit_batch. dry_run=true validates and reports without writing. Use when: a change arrives as a diff (git diff, a patch file, another tool's output) and must land completely or not at all — files created, modified, deleted or renamed. Avoid when: you have no diff (edit_file/edit_batch) or only need a new file (write_file). Not for directories or symbolic links. Output: dry_run: files[] {action, relative_path, hunks, bytes} plus added/modified/deleted/renamed counts; nothing is written. success: same list plus sha256_after per file. Failure: nothing is changed; data carries rollback_succeeded and, for a mismatching hunk, nearest_context lines for the file and hunk that failed.
Inputs: patch (required), reason, dry_run, expected_sha256.
cache_clearClear cachesADestructiveIdempotent
Clear in-process caches (all, read, info, list, search, recent, negative, graph, shell). Use when: reads look stale because a tool changed files outside Venira. Avoid when: normal flow: writes already invalidate caches. Output: cleared entry counts per cache.
Inputs: type.
change_impactChange impactARead-onlyIdempotent
List the files and symbols affected by changing given files or symbols (direction: dependents, dependencies or both). At least one of files/symbols; a symbol seed takes {name, relative_path} (file is an alias). Use when: you are about to rename or change something and need which files to read and which tests to run. Avoid when: you want the whole graph (dependency_graph). Output: affected[] {id, distance, path, confidence}, summary {affected_files, affected_symbols, tests_affected}, unresolved[] (the seeds that did not resolve: symbol, reason, next_step), stats {unresolved_imports, min_confidence, filtered_possible}. By default only exact/likely edges are traversed; pass min_confidence="possible" to follow name-matching guesses.
Inputs: depth, files, format, symbols, +4 more.
copy_pathCopy pathA
Copy a file, or a directory with recursive=true, inside the workspace. overwrite=true replaces an existing file; symbolic links and protected files inside a directory are skipped. Use when: you duplicate a file or folder, for example to start from a template. Avoid when: you move or rename (move_path). Output: from, to, kind, overwritten, entries, bytes, skipped_symlinks/skipped_protected when any. Missing source gives not_found, an existing target without overwrite gives conflict.
Inputs: to (required), from (required), reason, overwrite, +2 more.
createCreate directoryAIdempotent
Create a directory; missing parents are created unless create_dirs=false. Use when: you need an empty directory. For a file use write_file, which also creates parent folders. Avoid when: you edit existing content (edit_file). Output: directory_created {relative_path, created, parents_created}.
Inputs: relative_path (required), reason, create_dirs.
delete_pathDelete pathADestructiveIdempotent
Delete a file or directory (recursive=true is required for directories). Not undoable. Use when: you remove files or folders. Take a snapshot first when they are not in git. Avoid when: the target is uncertain (check with get_file_info or list_files). Output: entries_deleted, bytes_deleted. Missing path gives not_found.
Inputs: relative_path (required), reason, recursive.
dependency_graphDependency graphARead-onlyIdempotent
Build the import and reference graph for TypeScript/JavaScript, Python, Rust, Go, Java and Kotlin. format: json, dot or mermaid. Use when: you want module structure or what a subtree depends on. Narrow with relative_path, depth, languages. Avoid when: you need usages of one symbol (symbol_references) or the impact of an edit (change_impact). Output: nodes[], edges[] {from, to, type, confidence}, external[] (top 50), unresolved[] (top 10), stats {externals, unresolved_imports}, limited, truncated. dot and mermaid return data.graph.
Inputs: kind, depth, format, languages, +5 more.
diff_filesDiff filesARead-only
Unified diff between two workspace files. Use when: you compare two versions of a file, such as a backup and the current one. Avoid when: binary files, or git history (run git with shell_run). Output: lines_added, lines_removed, unified_diff, truncated.
Inputs: relative_path_a (required), relative_path_b (required), max_lines, context_lines.
edit_batchEdit batchA
Apply edits across one or more files all-or-nothing. Each item takes edit_file arguments (relative_path, old_text, new_text, ...). The first failure rolls back every touched file from an automatic snapshot and skips the rest. Use when: a change spans several files or sections and must land completely or not at all. Avoid when: you make one edit (edit_file). Output: success: per-edit {relative_path, replacements, sha256_after}. Failure: ok=false, error batch_failed, data {executed, skipped, rollback_succeeded, snapshot_id}.
Inputs: edits (required).
edit_fileEdit fileA
Replace exact text: old_text to new_text, or edits[] for several replacements in one file (edits[] wins). Use when: you make a targeted change. old_text must match exactly once unless replace_all=true. Pass expected_sha256 (read_file's sha256 or your last sha256_after) to refuse stale content and get a verified re-read. Avoid when: you rewrite the whole file (write_file) or change several files at once (edit_batch). Output: replacements, sha256_before, sha256_after, verified (when expected_sha256 is given). Failures leave the file unchanged: old_text_not_found (data.mismatch locates the first difference, data.context shows the nearby lines) and old_text_ambiguous (lists each match with context).
Inputs: relative_path (required), edits, reason, new_text, +3 more.
get_file_infoGet file infoARead-only
Return kind, size and modification time of a path. missing_ok=true answers ok with data.exists:false for a missing path instead of not_found (works inside read_batch items too).
Use when: you need to know whether a path exists or how big it is. Use missing_ok=true to probe existence without failing the call or the batch.
Avoid when: you need the content (read_file).
Output: kind, size_bytes, modified_unix_seconds, exists when missing_ok=true. Missing path gives not_found (or ok with exists:false and missing_ok=true).
Inputs: relative_path (required), missing_ok.
git_branchGit branchAIdempotent
List local (and optionally remote-tracking) branches, or create/switch/delete one. Use when: you need the current branch, want to branch off HEAD, switch branches, or prune a merged branch. Avoid when: you need the worktree state (git_status) or a remote PR’s head branch (pr_list). Output: list: current, branches[] {name, current, commit, upstream, track, remote}, branch_count. create/switch/delete: branch, commit/created/switched/deleted/force. Missing branch gives not_found; duplicate name gives conflict.
Inputs: from, name, force, action, +2 more.
git_commitGit commitA
Commit changes. Without paths: commit whatever is staged (paths given to it are staged first with git add). Amend is opt-in. Use when: your edits are ready to be committed locally. Avoid when: nothing should be committed (git only stages when paths are given, or you already staged). Merge/rebase and push are not performed. Output: sha, short_sha, subject, files_changed, files, amend. No staged changes gives invalid_request (pass paths or stage first).
Inputs: message (required), amend, paths, reason, +1 more.
git_diffGit diffARead-only
Parsed git diff (staged or worktree): files + hunks (old_start/lines, new_start/lines, section). Patch text is opt-in via include_patch=true. Use when: you need per-file hunk info for review/preview or a test, not free text. Avoid when: you need a raw unified blob (use include_patch=true or diff_files) or a PR diff (provider tools). Output: files[] {old_path|null, new_path|null, action (added|modified|deleted|renamed), binary, hunks[] {old_start, old_lines, new_start, new_lines, section}}, counts{}, patch_bytes, patch/patch_truncated when include_patch=true.
Inputs: paths, reason, staged, max_bytes, +2 more.
github_connectConnect GitHubA
Connect GitHub with Device Flow. action=start returns verification_uri and user_code: show them to the user, then action=poll with pending_id after they authorize. Tokens go to the encrypted vault and are never returned. Use when: the user wants to connect or replace the GitHub credential without pasting a token. Avoid when: you only need public read access, or a token is already configured. Output: start: verification_uri, user_code, pending_id, expiry. poll: pending | denied | expired | connected.
Inputs: action (required), pending_id, replace_existing.
git_logGit logARead-only
Local commit log, or per-line blame when blame=true with path. Filters: ref, author, grep, paths. Use when: you need recent commits or who last touched lines (blame). Avoid when: you need tags/remote refs only (git branch --all) or a remote CI’s log (ci_logs). Output: mode=log: commits[] {sha, short_sha, author, email, authored_at, committer, subject, body}, count. mode=blame: entries[] {line, commit, author, authored_at, summary}, lines.
Inputs: ref, grep, path, blame, +5 more.
git_stashGit stashA
Stash push/list/apply/pop/drop/show. Push stashes staged+unstaged tracked changes (add include_untracked=true for untracked files). Use when: you need to pause work to switch branches or commit selectively. Avoid when: you need to stash and keep a copy (stash keeps one; use apply over pop) or drop permanently (prefer apply, then commit). Output: push: pushed, message, selector, output. list: entries[] {selector, sha, subject}, count. apply/pop/drop: applied/dropped. show: files[], count.
Inputs: paths, action, reason, message, +2 more.
git_statusGit statusARead-only
Parsed local git status: branch, ahead/behind vs upstream, and every changed file with staged/unstaged/untracked state and staged/worktree status letters. Use when: you need the current repo state in a parseable form (before committing, stashing or opening a PR). Avoid when: you only need the raw command (shell_run) or a remote host’s CI status (ci_status). Output: ok, branch/detached, upstream (gone flag), ahead/behind, files[] {path, old_path?, staged, unstaged, untracked, unmerged, kind, status, index_status/worktree_status}, counts{}, clean.
Inputs: paths, reason.
healthHealth & metricsARead-only
Server diagnostics: version, workspace, security posture and warnings, caches, queue, running shells, latency, snapshot store, audit status. Use when: you debug slowness or errors, or want the security warnings before risky work. include_audit=false skips the audit query. Avoid when: normal file work. Output: One key per report section (see sections); with sections set, also sections_requested and sections_unknown.
Inputs: sections, include_audit.
list_filesList filesARead-only
List files and directories (depth 1-3, limit up to 200). include_ignored=true also lists ignored folders. Use when: you need the directory tree or want to confirm a path exists. Avoid when: you know the file (read_file) or want what changed lately (recent_files). Output: entries[] {relative_path, kind, size_bytes}, truncated.
Inputs: depth, limit, relative_path, include_ignored.
memoryMemoryADestructiveIdempotent
Read or overwrite this workspace's handoff note at /.venira/memory.md (action=read|write; write replaces it all, max 6000 bytes). Use when: a task starts or resumes (read, after recent_files); before you finish or run out of context (write: goal, decisions, files touched, next steps). Avoid when: lasting docs (write_file) or history (git_log). Plain text on disk: no secrets. Output: read: exists, content, bytes, updated_at_ms. write: replaced, previous_bytes, bytes, updated_at_ms. Over the cap or empty content: invalid_request, old note kept.
Inputs: action (required), content.
move_pathMove pathADestructive
Move or rename a file or directory inside the workspace. overwrite=true replaces an existing file, never a directory; create_dirs (default true) makes missing parents of to.
Use when: you rename or relocate files or folders. Not undoable: take a snapshot first when they are not in git.
Avoid when: you duplicate (copy_path) or remove (delete_path).
Output: from, to, kind, overwritten, entries, bytes. Missing source gives not_found, an existing target without overwrite gives conflict.
Inputs: to (required), from (required), reason, overwrite, +1 more.
outline_symbolOutline symbolsARead-only
List a source file's top-level symbols (functions, classes, types, interfaces) with line numbers. Use when: you want a file's structure before reading or refactoring it. Avoid when: you need usages (symbol_references), a text search (search) or the text itself (read_file). Output: total_symbols, symbols[] {name, kind, line, signature}.
Inputs: relative_path (required), language, max_symbols, include_classes, +1 more.
read_auditRead audit logARead-only
Read recent audit-log rows, newest first: what each job was asked and returned. Filter by session_id, operation, outcome, request_id, since_unix (seconds); verify=true checks the hash chain. Use when: you review what ran and how it ended, or look one job up by request_id. Avoid when: you want live metrics (health). Output: rows[] {session_id, operation, outcome, reason_code, reason, args_hash, command, request_id, started_at_ms, completed_at_ms, elapsed_ms, args_summary, result_summary, result_bytes}, count, truncated, chain_ok (verify=true). Output mode full adds redacted args and result per row; bulk text is kept as its length only. Timestamps are epoch milliseconds (since_unix filters in seconds). args_hash identifies the call, command is the redacted command line.
Inputs: limit, verify, outcome, operation, +3 more.
read_batchBatch readARead-only
Run up to 8 read-only ops in one call. operation is the short name (list_files|read_file|get_file_info|search) mapping to list_files|read_file|get_file_info|search; arguments hold exactly that tool's parameters. Use when: you need 2+ reads or mixed read steps. Items run in order and one failing item does not stop the rest. Avoid when: a single read (read_file) or any edit (edit_batch). Output: responses[] each {ok, response | error}, total_bytes_returned.
Inputs: requests (required).
read_fileRead fileARead-only
Read a text file, whole or by line range (start_line/end_line, 1-based; ranges[] for several disjoint ranges of one file). Use when: you need one file's content. When truncated, call again with start_line=next_start_line. Avoid when: you need 2+ files (read_batch) or only size/mtime (get_file_info). Output: text (as preview in compact mode; preview_truncated marks a cut), first_line, last_line, total_bytes, truncated, next_start_line (when truncated). sha256 hashes the whole file and is safe as expected_sha256; text_sha256 covers only the returned text. Missing path gives not_found.
Inputs: relative_path (required), ranges, end_line, max_bytes, +2 more.
recent_filesRecent filesARead-only
List recently modified files, newest first, plus session_edits (files you wrote in this session). Use when: you start or resume a task, or finished a build, format or git step and want to see what changed. Feed the top paths into read_batch. Avoid when: you need the full tree (list_files) or a content search (search). Output: entries[] {relative_path, size_bytes, modified_ago_seconds}, session_edits, truncated.
Inputs: depth, limit, relative_path, include_ignored.
searchSearch workspaceARead-only
Search by kind: file_name, directory_name, literal_content (regex=true for regex) or definition (symbol declarations). queries instead ranks matching lines by several weighted patterns (must/weight).
Use when: you must locate code, strings or symbols before reading. Keep relative_path narrow: a scan stops at 50000 files.
Avoid when: you know the path (read_file), want a file's structure (outline_symbol), a symbol's usages (symbol_references) or an executable on PATH (shell_run: where <name>).
Output: hits[] {relative_path, line_number, snippet}, complete, total_match_lines, files_matched. With queries: hits also carry score/matched, plus total_files/total_hits. No match is ok with empty hits.
Inputs: glob, kind, limit, query, +11 more.
secretManage secretsADestructiveIdempotent
Store and inspect tokens without exposing them (AES-256-GCM at rest). action: set | get (metadata only) | list | delete. Inject into commands with shell_run secret_env=[NAME]; the GitHub tools read GITHUB_TOKEN on their own. Use when: you save a non-GitHub token, check expiry or rotation, or remove one. Prefer value_env over value so the secret never appears in chat. Avoid when: the value is plain config (use .env or the config file). reveal=true prints plaintext and needs VENIRA_SHELL_MODE=permissive or off. Output: set: name, length, expires_at, days_left. get and list: metadata only.
Inputs: name, value, action, reason, +4 more.
shell_cancelShell cancelADestructiveIdempotent
Kill a running command and its child processes. Needs run_id and kill_key from shell_run. Use when: a command hangs or its result is no longer needed. Avoid when: the run already finished (shell_status). Output: accepted, cleanup_complete.
Inputs: run_id (required), kill_key (required).
shell_cancel_sessionShell cancel sessionADestructiveIdempotent
Kill every shell run started in this session. Use when: you tear down a stuck session with several running commands. Avoid when: only one run must stop (shell_cancel). Output: cancelled_run_ids[], count.
Inputs: no named parameters.
shell_runShell runADestructive
Run a shell command in the workspace (shell, relative_cwd, timeout_s). Default is background: returns run_id, poll shell_status. background=false blocks until exit and returns stdout/stderr. Use when: you build, test, run git or install packages. background=false for short commands you need now. Avoid when: you read or edit files (file tools) or run a tiny JS calculation (execute_js). Output: run_id, kill_key, running, exit_code, timed_out, stdout/stderr (background=false) or stdout_tail/stderr_tail. ok=true only means the call ran; status (completed|failed|running|cancelled) and command_status describe the command. shell_path/shell_kind name the binary that ran it (on Windows bash may be the WSL launcher). approval_required: ask the user to approve, then retry once with approval_id. repeated_failure: the identical invocation already failed; read data.previous.stderr_tail, then change the command or pass retry_failed=true.
Inputs: command (required), shell, reason, dry_run, +8 more.
shell_statusShell statusARead-only
Return the state and output tail of a shell run. wait_seconds (0-300) waits up to that long for it to finish. Use when: after a background shell_run: poll until running=false, then read exit_code. Avoid when: you have no run_id yet. Output: running, exit_code, stdout_tail, stderr_tail. Unknown run_id gives not_found (run ids only live for this session).
Inputs: run_id (required), wait_seconds.
snapshotWorkspace checkpointADestructive
Checkpoint and roll back workspace files. action: create (label, paths) | list | restore (id) | delete (id) | mirror (copy to VENIRA_SNAPSHOT_MIRROR_DIR). Use when: before multi-file refactors or overwriting/deleting files git does not hold. Keep paths narrow and check file_count and skipped. Roll back with restore dry_run=true, then restore with verify=true. Avoid when: tiny single-file edits or states git already holds. Output: create: id, file_count, total_bytes, truncated, skipped[]. restore: restored[], deleted_count, skipped[].
Inputs: id, label, limit, paths, +9 more.
switch_workspaceSwitch workspaceAIdempotent
Re-root the workspace to another directory at runtime. Follows VENIRA_SECURITY_PROFILE: trusted/off (or VENIRA_UNRESTRICTED=1) switch anywhere existing; strict/balanced only inside VENIRA_WORKSPACE_ROOTS (unset = spawn only). Use when: the client spawned the server once (e.g. Claude Desktop) and the user changed to a different project folder; switch instead of restarting the client. Avoid when: one-shot tasks in the spawn directory, or under strict/balanced without VENIRA_WORKSPACE_ROOTS (the call is refused). Output: workspace_root (the new root), allowed_roots. All subsequent path guards and caches operate on the new root.
Inputs: root (required), reason.
symbol_referencesSymbol referencesARead-only
Find occurrences of a symbol name. scope=file needs relative_path (one file); scope=workspace (default) searches all files. Use when: you check where a symbol is used before renaming or changing it. Avoid when: you only need its declaration (outline_symbol) or arbitrary text (search). Output: count (matches found), returned (how many came back), omitted (cut by the cap), scan_limit (workspace only), references[] {relative_path, line_number, context}.
Inputs: symbol_name (required), limit, scope, relative_path, +1 more.
trace_statusTrace statusARead-only
Show recent traced tool calls (tracing is always on). Use when: you want to see what ran recently without opening the log file. Avoid when: tracing is off (the buffer is empty). Output: enabled, file, buffered, recent[] (newest first, timestamp_ms is epoch milliseconds).
Inputs: limit.
write_fileWrite fileADestructive
Write a file. mode=create (fails if it exists), overwrite, or append. create_dirs=true creates parent folders. Use when: you create a file, replace one entirely, or append. expected_sha256 refuses the write if the file changed since you read it. Avoid when: you change a few lines (edit_file). overwrite is immediate and not undoable: snapshot first when the file is not in git. Output: action (created|overwritten|appended), bytes_written, sha256_after. mode=create on an existing path gives conflict.
Inputs: content (required), relative_path (required), mode, reason, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 38 tools
Most tools are clearly differentiated by resource and action, and the Use when/Avoid when notes explicitly route between overlapping areas such as read_file vs read_batch, edit_file vs edit_batch vs apply_patch, and search vs symbol_references. A few clusters remain close—batch vs single-file operations, snapshot vs git, and shell_run vs shell_status/cancel—but the descriptions make the intended choice clear.
All names use snake_case, but ordering is mixed: verb_noun (read_file, list_files), noun_verb (cache_clear, shell_cancel), domain-prefixed nouns (git_status, git_diff), and bare nouns (memory, snapshot, secret, health). It remains readable and domain-grouped, but not a single predictable pattern.
38 tools is well above the 25-tool threshold for 'too many' and includes several auxiliary/admin tools (cache_clear, trace_status, health, read_audit, switch_workspace) alongside core file, git, and shell operations. The broad coding-workspace purpose justifies many of them, but the surface is heavy and increases selection cost.
Core file lifecycle, search/code-intel, local git, shell, snapshots, memory, and audit are well covered with no obvious dead ends. Minor gaps remain around remote git operations (push/pull), GitHub API actions beyond connect, and higher-level test/lint workflows, though shell_run can cover many of these.
Maintenance
Related MCP Connectors
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Securely search and manage workspace context files for AI agents and teams.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
A real-time, multiplayer filesystem for agents and humans: shared files, live edits, history.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to develop within a local project workspace by reading and modifying files, running commands and tests, checking Git state, and persisting progress as history sessions that can be restored in later conversations.Apache 2.0
- FlicenseAqualityBmaintenanceEnables coding agents to perform workspace-confined file operations, read-only Git inspection, and structured shell commands, while requiring out-of-band human approval for mutations and external executions and maintaining an audit trail.143-
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to safely read, search, understand, and edit local project code and files, with Git inspection, code indexing, and controlled command execution within permissioned workspaces.8 npm6MIT
- AlicenseAqualityBmaintenanceEnables coding agents to safely inspect and modify project files within explicitly allowed workspace roots, with controls for file operations, git status/diff, and optionally allowlisted command execution.11Apache 2.0