Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
VENIRA_PRETTYNoSet to "1" for pretty-printed JSON in tool results.0
VENIRA_DATA_DIRNoWhere the audit DB (venira.db) is created/updated.<workspace>/data
VENIRA_WORKSPACENoRoot of the workspace. All relative paths resolve against this; absolute paths outside it are rejected unless unrestricted.process.cwd()
VENIRA_SESSION_IDNoSession tag; audit rows are grouped by it.auto (opencode-<pid>-<rand>)
VENIRA_OUTPUT_MODENoOutput mode: full, compact, or summary.full
VENIRA_UNRESTRICTEDNoSet to "1" to disable workspace locking. Do not set in production.0
VENIRA_DEBUG_STARTUPNoSet to "1" to send startup errors to stderr instead of the protocol-safe stdout event.0
VENIRA_DEFAULT_SHELLNoDefault shell for project_shell_run: powershell, cmd, or bash.platform default
VENIRA_LIST_CACHE_MSNoTTL for directory listing cache.1500
VENIRA_RECENT_CACHE_MSNoTTL for recent-files cache.2000
VENIRA_SEARCH_CACHE_MSNoTTL for search result cache.3000
VENIRA_BATCH_ITEM_BYTESNoPer-item cap inside project_read_batch.524288
VENIRA_READ_CACHE_BYTESNoBudget 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

  1. Two or more reads, or mixed read-only steps -> read_batch (max 8, sequential + cached). Do not fire many single reads.

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

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

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

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

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

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

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

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

  10. Pull requests -> pr_create (open), pr_comment (thread reply, or an inline note with path + line), pr_merge (land, optionally delete the branch).

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

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

  13. Starting an unfamiliar task -> plan_read_batch(task_description, files_hint?) and run steps[0] (expert mode only; otherwise call search directly).

  14. Debug latency/errors or check host/audit DB -> health.

  15. Unsure which tool exists -> use the Code Mode tool-discovery helper (findTools; named search in older builds), not a Venira tool.

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

  17. 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_access OAuth 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_command or 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

CapabilityDetails
tools
{
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

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

searchA

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.

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

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

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.9/5.0

Scored across 38 tools

Disambiguation4/5

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.

Naming Consistency3/5

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.

Tool Count2/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessNo recent community issues