Venira
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| VENIRA_PRETTY | No | Set to "1" for pretty-printed JSON in tool results. | 0 |
| VENIRA_DATA_DIR | No | Where the audit DB (venira.db) is created/updated. | <workspace>/data |
| VENIRA_WORKSPACE | No | Root of the workspace. All relative paths resolve against this; absolute paths outside it are rejected unless unrestricted. | process.cwd() |
| VENIRA_SESSION_ID | No | Session tag; audit rows are grouped by it. | auto (opencode-<pid>-<rand>) |
| VENIRA_OUTPUT_MODE | No | Output mode: full, compact, or summary. | full |
| VENIRA_UNRESTRICTED | No | Set to "1" to disable workspace locking. Do not set in production. | 0 |
| VENIRA_DEBUG_STARTUP | No | Set to "1" to send startup errors to stderr instead of the protocol-safe stdout event. | 0 |
| VENIRA_DEFAULT_SHELL | No | Default shell for project_shell_run: powershell, cmd, or bash. | platform default |
| VENIRA_LIST_CACHE_MS | No | TTL for directory listing cache. | 1500 |
| VENIRA_RECENT_CACHE_MS | No | TTL for recent-files cache. | 2000 |
| VENIRA_SEARCH_CACHE_MS | No | TTL for search result cache. | 3000 |
| VENIRA_BATCH_ITEM_BYTES | No | Per-item cap inside project_read_batch. | 524288 |
| VENIRA_READ_CACHE_BYTES | No | Budget for read and info caches. | 67108864 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Venira coding tools operate on the workspace /app. Every call returns a JSON envelope: { ok, status, request_id, kind, data, truncated?, summary?, hint?, next_actions?, cached?, trimmed?, command_status?, elapsed_ms }. On failure: { ok:false, error:{ code, message, retryable }, hint, next_actions? } and the MCP result has isError=true. A read_batch with any failed items returns ok=false/status=partial; inspect each data.responses entry. For shell_run, ok=true means the tool call completed; command_status separately reports running/succeeded/failed/cancelled/unknown. Read "hint" and "next_actions" first; they say how to recover.
Decision tree
Two or more reads, or mixed read-only steps -> read_batch (max 8, sequential + cached). Do not fire many single reads.
One file -> read_file; large file -> start_line/end_line, or ranges=[{start_line,end_line},...] for several disjoint ranges of the same file (max 16); follow next_start_line.
Find code -> search (kind=literal_content or definition; pass queries=[{pattern, must?, weight?}] to rank files by AND/OR/NOT patterns instead of a single substring), then read_file with ranges around the hits (or several files in one read_batch).
Directory tree -> list_files (depth 1..3, limit <=200). "What changed lately / what did the user or a command just touch?" -> recent_files (cheap; make it a habit).
Code structure -> outline_symbol; usages of one symbol -> symbol_references; whole-file dependencies -> dependency_graph; "what breaks if I edit this?" -> change_impact (files=[...] or symbols=[...], direction=dependents).
Write whole file -> write_file; small precise change -> edit_file; a batch spanning several files that must land completely or not at all -> edit_batch (text replacements) or apply_patch (unified diff: create/modify/delete/rename; dry_run=true to validate first, automatic rollback on failure); empty directory -> create; rename or relocate -> move_path; duplicate -> copy_path; delete -> delete_path (destructive, not undoable). Local git -> git_status/diff/log (blame=true) to inspect, git_commit/git_branch/git_stash to mutate (audit reason; push never happens here - plain push runs; force/delete/URL pushes need approval).
Before multi-file, cross-file, refactor/rename or otherwise hard-to-reverse work -> create a scoped snapshot with a descriptive label, retain its returned id, inspect file_count/truncated/skipped, then proceed. For rollback, run restore with dry_run=true first; it previews path/size only and cannot detect same-size content changes. Treat all captured files in scope as potentially overwritten; inspect any newer user edits, then restore the exact id with verify=true and delete_extra=false. Never set delete_extra=true unless deleting post-checkpoint files is explicitly part of the task. Skip snapshots for a tiny, easy-to-recreate single-file edit.
Build/test/long command -> shell_run (returns run_id immediately), then poll shell_status with wait_seconds 5..300 until running=false; shell_cancel to stop. Need the final output in this call? Pass background=false: it blocks until the command exits (do not start other work while waiting); keep it under the client request timeout or use the async run plus polling.
GitHub connection -> github_connect action=start, show the user the GitHub verification link/code, and poll only after they authorize. Never ask for a token in chat. Other tokens -> secret (action=set|get|list|delete); never paste a key into a command.
Pull requests -> pr_create (open), pr_comment (thread reply, or an inline note with path + line), pr_merge (land, optionally delete the branch).
CI -> ci_status (runs + jobs; pr/ref for branch-protection check-runs), ci_control (explicit cancel/retry_failed with run_id + reason; provider may return unsupported), ci_trigger (workflow_dispatch), ci_logs (bounded tail), ci_wait (bounded long-poll; failure tail).
Something failed and the cause is unclear -> explain_error with error_text or log_tail; then apply the first diagnosis (expert mode only; non-expert agents read the error text + hint, which is enough for most cases).
Starting an unfamiliar task -> plan_read_batch(task_description, files_hint?) and run steps[0] (expert mode only; otherwise call search directly).
Debug latency/errors or check host/audit DB -> health.
Unsure which tool exists -> use the Code Mode tool-discovery helper (findTools; named search in older builds), not a Venira tool.
Switching project mid-session -> switch_workspace with the absolute path of the new project folder (VENIRA_SECURITY_PROFILE trusted/off switch any existing directory; strict/balanced only inside VENIRA_WORKSPACE_ROOTS, which unset locks to the spawn workspace). All path guards and caches follow the new root; the client does not need to respawn the server.
Context that must outlive this chat -> memory. action=read at the start of a task (after recent_files) to pick up what the previous AI left; action=write before you finish or when context runs long. Write replaces the whole note, so keep it short and current: goal, decisions, files touched, next steps. No secrets.
Rules
Make recent_files a reflex, not a last resort: call it (limit 10..20) at the start of a task, when resuming or after context loss, before editing a file the user may have changed, and after shell_run / a build / a formatter / git to see what really changed. Its session_edits field lists what you already wrote this session. Then feed the top paths straight into read_batch. Use it instead of listing a whole tree or re-searching. VENIRA_TOOL_MODE=core lists only a small set (shell, execute_js, read_file/search/list_files, recent_files, outline_symbol, edit/write/create/move/delete, snapshot, git, memory): ignore guidance above for tools you do not see, such as read_batch.
Prefer Venira for read-heavy/batch work; single tiny native operations are fine either way.
Paths are workspace-relative (absolute inside the workspace also works). Never invent @grant paths unless list_files returned them.
read_batch and list_files/search results are cached briefly; mutations invalidate caches automatically.
Probe whether a path exists with get_file_info missing_ok=true (batch-safe: a missing path answers ok with data.exists:false instead of failing the batch).
dependency_graph and change_impact are disabled in VENIRA_TOOL_MODE=core. Their node ids are workspace-relative; change_impact reports tests separately as tests_affected, and ambiguous bare symbol names downgrade affected entries to confidence=possible (pass {name, file} to pin one).
ci_wait is a bounded long-poll, not a push notification (MCP stdio cannot wake the model): terminal=false means "nothing changed before the timeout", so call it again with the same selector; keep timeout_s below the client request timeout (~60s). It is unqueued, so other tools keep working, and network access follows the OS/container policy.
Pass
reason("why", e.g. "fix null pointer at line 45") on write/edit/delete/create/snapshot/pr/ci to make the audit trail readable; when omitted the backend records an autogenerated "auto: " reason. Required only when VENIRA_SECURITY_PROFILE=strict. CI control actions require a reason. Read it back with read_audit.Snapshot discipline: before write_file mode=overwrite, multi-section/multi-file edits, edit_batch on existing files, hard-to-reverse shell/JS workspace changes, and every delete_path call, create a labeled scoped checkpoint, keep its id, and confirm required files were captured (file_count, truncated, skipped) before mutating. Before rollback, use restore dry_run=true; it previews path/size only and cannot detect same-size content changes. Treat all captured files in scope as potentially overwritten and inspect newer user edits; restore only the exact checkpoint id with verify=true and delete_extra=false. Never enable delete_extra unless that deletion is explicitly requested. Checkpoints are content-addressed/deduplicated and SHA-256 verified by default; new-file creation and disposable generated output do not need a checkpoint.
Secrets are encrypted at rest and never logged: secret get returns metadata (length + sha256 prefix, expires_at/days_left, last_used_at/use_count), values reach processes only via secret_env, and shell output/audit text is scrubbed of stored values. Expired secrets fail with secret_expired before a child starts.
Git provider payloads and responses are checked locally with Secretlint's recommended credential rules. A detected secret blocks the outbound request or withholds the provider response; scanner errors fail closed. A response-side block can happen after a mutation completed, so never retry solely because of that block. Never include a real credential in a PR, comment, or CI input.
Git provider tools (GitHub, GitLab, Bitbucket) resolve the repo from
repo-> VENIRA_GIT_REPO (legacy VENIRA_GITHUB_REPO) -> git.repo in venira.config.json -> .git/config origin; the token comes from a stored secret (GITHUB_TOKEN for GitHub) or an env var (VENIRA_GIT_TOKEN, or GITHUB_TOKEN / VENIRA_GITHUB_TOKEN for GitHub) (expiry is enforced, use tracking is recorded). outbound network access follows the OS/container policy.github_connect uses GitHub Device Flow and the
repo offline_accessOAuth scopes for private-repository support and refreshable access. The access/refresh tokens are stored encrypted locally and never returned to the agent; users authorize Venira at github.com.explain_error and plan_read_batch (expert mode only) are deterministic (no model call): explain_error maps signatures to next_actions, plan_read_batch returns a ready batch call.
Never loop on a non-retryable error (not_found, scope_denied, invalid_request, sensitive_result, audit_unavailable). Read the hint and change the request or tell the user.
Repeated failure: when shell_run answers repeated_failure, the identical invocation already failed in this session and was NOT run again. Read data.previous.stderr_tail, fix the cause, then change the command or its inputs - a different command, shell, cwd or input is a different invocation and runs normally. Pass retry_failed=true only when you deliberately want the identical command to run again.
Freshness exception: stale_content is the one case where you MUST re-read a file. Read it again with read_file, rebuild the patch against the current content and send the new sha256 as expected_sha256; never replay the same edit unchanged. read_file.sha256 is always the whole-file hash (sha256_scope: file) and is safe to send as expected_sha256; text_sha256 covers only the returned slice.
Output modes: VENIRA_OUTPUT_MODE=full|compact (default full). compact trims payloads over 8 KiB and marks them; generic data uses data.preview_text. Use full when you need complete data.
Security profile: VENIRA_SECURITY_PROFILE=strict|balanced|trusted|off (default balanced) sets the shell policy and per-call JS approval together; VENIRA_SHELL_MODE=balanced|strict|permissive|off is an advanced override. Hard-deny rules stay active in strict/balanced; permissive turns hard-deny into an approval request; off disables all shell checks, hard-deny included (operator opt-in, trusted environments only).
Approvals: when shell_run or execute_js returns approval_required, STOP. Tell the user the approval_id and data.approval.approve_command (a human grants it via
data.approval.approve_commandor client elicitation); do not loop, poll or try to approve it yourself. After the user confirms, retry once with data.approval.retry_with. Use shell_run dry_run=true to learn beforehand whether a command would be allowed, asked or denied (nothing runs). approval_wait_s (<=45) makes the call wait for the human and run in the same call; keep it under the client request timeout. approval_token was removed; use approval_id.Named shell overrides require both an operator allowlist (VENIRA_SHELL_OVERRIDES) and a per-call override name plus non-empty reason; they are narrow and audited.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_filesA | 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. |
| read_fileA | 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. |
| get_file_infoA | Return kind, size and modification time of a path. |
| searchA | Search by kind: file_name, directory_name, literal_content (regex=true for regex) or definition (symbol declarations). |
| recent_filesA | 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. |
| read_batchA | 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. |
| write_fileA | 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. |
| edit_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). |
| edit_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}. |
| delete_pathA | 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. |
| move_pathA | 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 |
| copy_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. |
| apply_patchA | 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. |
| shell_runA | 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. |
| shell_statusA | 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). |
| shell_cancelA | 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. |
| createA | 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}. |
| healthA | 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. |
| cache_clearA | 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. |
| trace_statusA | 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). |
| memoryA | 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. |
| read_auditA | 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. |
| switch_workspaceA | 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. |
| shell_cancel_sessionA | 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. |
| outline_symbolA | 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}. |
| diff_filesA | 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. |
| symbol_referencesA | 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}. |
| dependency_graphA | 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. |
| change_impactA | 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. |
| snapshotA | 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[]. |
| git_statusA | 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. |
| git_diffA | 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. |
| git_logA | 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. |
| git_branchA | 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. |
| git_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). |
| git_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. |
| github_connectA | 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. |
| secretA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.