What Osmogrep Is

Osmogrep is a Rust-native terminal UI for running autonomous AI agents, with structured logging, tool invocation, and streaming execution control.

• A local-first AI agent
• Running inside your terminal
• Operating on a real Git repository
• Using explicit, auditable tools

Core Concepts

The agent acts through tools:

• Shell — run real commands
• Search — grep / ripgrep style search
• Read File — inspect file contents
• Write File — make concrete edits

UI

Osmogrep ships with a high-performance terminal UI:

• Streaming agent output

• Tool calls rendered hierarchically

• Scrollable execution history

• Clear separation between:

  • user input
  • tool execution
  • agent output

Model Support

Osmogrep works with any OpenAI-compatible API, including:

• OpenAI
• Anthropic-compatible endpoints
• Local models via Ollama

Model choice is orthogonal to execution correctness.

Installation

From crates.io

cargo install osmogrep

Latest from GitHub

curl -fsSL https://raw.githubusercontent.com/kaushal07wick/osmogrep/master/install.sh | sh

Usage

Run inside any Git repository:

osmogrep

Run PR/Issue triage for a GitHub repository:

osmogrep triage \
  --repo owner/repo \
  --state open \
  --limit 3000 \
  --deep-review-all \
  --incremental \
  --state-file .context/triage-state-owner_repo.json \
  --vision ./VISION.md \
  --out triage-report.json

GITHUB_TOKEN is recommended for higher API limits.

Apply triage actions (labels/comments) to GitHub:

osmogrep triage \
  --repo owner/repo \
  --state open \
  --limit 3000 \
  --incremental \
  --vision ./VISION.md \
  --comment-actions \
  --apply-actions \
  --action-limit 100 \
  --out triage-report.json

Triage now supports:

• Incremental runs via --incremental + --state-file
• Duplicate detection with lexical + semantic token scoring
• Optional action planning/execution (label, comment) with --apply-actions

You interact with the agent directly:

• Ask it to inspect code
• Search for symbols
• Modify files
• Run commands
• Validate changes

All actions are visible and reversible via Git.

Voice Input (vLLM Realtime + iPhone Mic)

Osmogrep can accept live voice input via the vLLM realtime API and stream transcriptions directly into the input box.

Requirements

• GPU machine capable of running vLLM
• vLLM server with realtime support enabled
• iPhone (or any browser mic) to capture audio
• ngrok (or any HTTPS tunnel) for iOS mic access

vLLM Server

Run vLLM with a realtime-capable model (example):

vllm serve mistralai/Voxtral-Mini-4B-Realtime-2602 \
  --enable-realtime \
  --host 0.0.0.0 \
  --port 8000

Osmogrep Voice Proxy

Osmogrep opens a websocket proxy on 7001 and forwards to vLLM:

VLLM_REALTIME_PROXY_LISTEN=0.0.0.0:7001 \
VLLM_REALTIME_URL=ws://127.0.0.1:8000/v1/realtime \
VLLM_REALTIME_MODEL=mistralai/Voxtral-Mini-4B-Realtime-2602 \
VLLM_REALTIME_SILENCE_MS=1200 \
osmogrep

Reverse Proxy (single HTTPS endpoint)

Because iOS requires HTTPS for getUserMedia, run the local reverse proxy:

node tools/ws_reverse_proxy.js

This serves mic.html and proxies /v1/realtime to localhost:7001.

ngrok (HTTPS tunnel)

Run a single tunnel to the reverse proxy:

ngrok http 8080

Open the HTTPS URL on iPhone:

https://<ngrok-url>/mic.html

What You Get

• Live transcription shown above the input box
• Final sentence inserted directly into the input box
• Press Enter to send as a normal prompt

Commands

Osmogrep supports a small, explicit set of slash commands. Anything else is sent directly to the agent.

Slash Commands

Command	Description
/help	Show available commands
/clear	Clear execution logs
/key	Enter OpenAI API key mode
/model	Show/switch provider + model
/test	Run auto-detected project tests
/undo	Revert last agent file change
/diff	Show session file changes
/mcp	Show MCP status and servers
/providers	Show available model providers
/triage	One-command PR/Issue triage workflow (streaming + markdown output)
/gh	GitHub CLI status + PR/Issue/Triage views
/new	Start a fresh conversation
/approve	Toggle dangerous tool auto-approve
/nv	Open Neovim + Osmogrep split in tmux
/quit	Stop the currently running agent
/q	Alias for /quit
/exit	Exit Osmogrep

During agent execution:

• Esc requests cancellation instead of exiting.
• Dangerous tools (run_shell, write_file, edit_file) prompt for approval unless /approve is enabled.
• /model <provider> <model> [base_url] switches runtime model config.
• /test <target> runs targeted tests (e.g. cargo test foo, pytest tests/test_x.py).
• Session state and undo checkpoints are persisted per-repo under ~/.config/osmogrep/sessions/.

/gh triage defaults are tuned for high-volume repos:

• --state open --limit 3000 --deep-review-all --incremental
• auto state file: .context/triage-state-<owner_repo>.json
• auto report outputs:
  • .context/triage-report-<owner_repo>.json
  • .context/triage-brief-<owner_repo>.md
• auto --vision ./VISION.md when VISION.md exists at repo root

Agent toolset now also includes: run_tests, list_dir, git_diff, git_log, regex_search, web_fetch, find_definition, find_references, git_commit, patch, notebook_edit, web_search, diagnostics, mcp_call.

/nv notes:

• If not already inside tmux, Osmogrep bootstraps a tmux session automatically.
• Left pane runs nvim; right pane runs Osmogrep.
• Managed Neovim UX is auto-installed by install.sh (theme, tree, icons, treesitter, LSP setup).
• /nv toggle hides/shows the nvim pane in the current tmux window.
• Exit helpers: /nv help (shows :q, :wq, :qa!, pane navigation, tmux detach).

Repository-specific behavior can be guided with .osmogrep.md at repo root.

Hooks can be configured in ~/.config/osmogrep/config.toml:

[hooks]
pre_shell = "echo running {cmd}"
pre_edit = "echo editing {path}"
post_edit = "cargo check -q"

MCP scaffold can also be configured in the same file:

[mcp]
enabled = true
default_server = "docs"

[mcp.servers.docs]
cmd = "node /path/to/your-mcp-bridge.js"
timeout_ms = 30000

The agent tool mcp_call passes:

• OSMOGREP_MCP_SERVER
• OSMOGREP_MCP_METHOD
• OSMOGREP_MCP_ARGS (JSON)

License

MIT License.