Deterministic local repository context, impact analysis, and merge-readiness evidence for AI agents.
Model Context Protocol (MCP) Server: io.github.BASHBOP/otito
This MCP server provides deterministic local repository context for AI agents. It focuses on impact analysis and merge-readiness evidence, supporting workflows that need consistent repository-derived information and verifiable context before merging changes.
🛠️ Key Features
Deterministic local repository context
Impact analysis
Merge-readiness evidence
🚀 Use Cases
Supplying AI agents with repeatable repository context
Performing change impact assessment on local repositories
Verifying readiness for merges using evidence from the repository
⚡ Developer Benefits
Deterministic outputs for local repository context
Clear support for impact analysis
Evidence-based merge readiness checks for agent workflows
⚠️ Limitations
Only the provided summary is available: no tool count, topics, or additional implementation details were specified
An agent's output is bounded by two things: the model and the harness around it. The harness includes the prompts, the context it's given, the codebase it works in, and the gates it must pass before code merges. You don't control the model. You control the harness, and a tighter harness lets a cheaper model do the same work with fewer wasted tokens.
Òtítọ́ is that harness layer. It is local-first, deterministic, and model-agnostic: it discovers repositories, builds local indexes, generates task-aware context before an agent edits, scores how much a change actually touches, and gates merge readiness. It works the same way every time, with no server, no account, and no code leaving the machine. Because it depends on software fundamentals rather than any one model, the harness you build today keeps working as models change underneath it.
It does not try to replace opensrc, code-structure, Daytona, or Harnss. It gives developers and coding agents a single CLI that can:
Deterministic merge gates are the differentiated core. This is the human-in-the-loop checkpoint that a model cannot grade for itself:
score merge readiness for local changes and pull requests with one review_gate tool (gate on the CLI)
resolve CODEOWNERS to required reviewers and surface owner-decision warnings
check branch-protection expectations and required checks before merge
generate actionable PR review context from git diffs and optional GitHub comments
Local-first context feeds the gates:
inspect a repository
discover and index local repositories
maintain a local catalog and search across it
generate task-aware context packets before an agent plans or edits
generate AST-backed JSON-first code maps for agents
generate a setup/validation/runtime harness for a repo
produce Markdown or JSON reports
estimate context-token size for generated artifacts
run an MCP server for agent hosts with a persisted per-user index cache that never dirties an inspected repository
expose simple agent-friendly tool metadata
check tool availability
generate TypeScript structure HTML through code-structure
search dependency source through opensrc
Documentation
The published MkDocs site is a practical discovery and delivery guide:
Code maps use the TypeScript compiler for JS/TS and dedicated language extractors for Go, C#, Python, Java, Ruby, and Rust (see src/lib/code-map/ast-languages.js). Optional external tools are only needed for dependency-source lookup and HTML structure reports.
Install the published package from npm:
bash
npm install -g @bashbop/otito
otito doctor
otito index ~/projects --discover
otito context "add a new MCP tool" --path .
You can also run a command without a global install:
bash
npx -y @bashbop/otito doctor
For source development:
bash
git clone https://github.com/BASHBOP/otito.git
cd otito
npm ci
npm run ci
node src/cli.js doctor
The current release is available through npm, GitHub Releases, and the MCP Registry as io.github.BASHBOP/otito.
Changed files, risk prompts, review targets, and test hints
Index local projects
otito index ~/projects --discover
External per-user indexes plus a local catalog
Search indexed repos
otito search "events controller"
Ranked matches across paths, domains, routes, imports, exports, and symbols
Run the MCP server
otito mcp
Stdio MCP server exposing otito tools
Track usage & performance
otito dashboard
Self-contained HTML from an opt-in local usage log (off by default)
For Claude Desktop, VS Code, Cursor, and generic stdio client snippets, see MCP and Agent Workflows.
otito vs alternatives
Approach
Strengths
Where otito differs
Sourcegraph / Cody context
Powerful hosted code search and embedding-based context across an org
otito is local-first and deterministic: no server, no account, no code leaves the machine, and the same query always yields the same packet
Hand-written CLAUDE.md / rules files
Curated, intent-rich guidance
Hand-written context goes stale; otito regenerates context from the actual code (symbols, imports, routes, tests) on every run and complements a short CLAUDE.md
grep / ripgrep
Fast, universal text matching
otito ranks whole files by task intent across paths, symbols, exports, and tests, then adds patterns and validation commands. The result is a context packet, not a list of matching lines
Quality Gates
Use the full gate before opening a pull request or publishing a release:
bash
npm run ci
The gate runs:
npm run format:check
npm run lint
npm run typecheck
npm run version:check
npm test
npm run test:coverage
npm run eval:accuracy
npm run eval:harness
npm run audit
npm run smoke
Coverage currently gates source files at 70% lines, 60% branches, and 75% functions. Generated artifacts under .otito/ are ignored by git, linting, and formatting; keep durable reports there instead of committing them.
The v1.1.0 harness execution evaluation runs only vetted install, test, typecheck, and build commands against committed fixtures. It disables install lifecycle scripts, applies timeouts, and never executes inferred commands from a customer repository.
otito follows Semantic Versioning. Pull requests should identify whether they are no-version-impact, patch, minor, or major changes; maintainers apply the final package version during release.
For longer trust-layer work, use the Builder-Founder Operating Loop to keep every session tied to context, focused changes, visible gates, human decisions, and durable evidence.
Contributing
Contributions are welcome. Start with CONTRIBUTING.md, open an issue or draft PR for substantial changes, and run npm run ci before requesting review.
All code changes must be reviewed by a maintainer/code owner before merge. The protected main branch requires maintainer approval, passing quality gates, and resolved PR conversations.
Merge gate (gate is the canonical v2 command; pass / pass-pr remain as legacy aliases):
bash
otito gate . --base origin/main # local gate (no GitHub)
otito gate . --staged --base origin/main # staged-path evidence, suitable for pre-commit hooks
otito gate . --base origin/main --request "update the greeting" --min-convergence 80
otito converge "update the greeting" --path . --base HEAD --staged --json # exact change-subject receipt
otito gate --pr 123 --path . # GitHub PR gate via gh
In staged mode, changed-path, risk, secret and convergence evidence use the exact Git index tree. Exact-subject source analysis streams raw Git blobs and fails closed above 5,000 source files or 64 MiB. Release, validation-command and optional analyzer checks still inspect the working tree and are reported outside the convergence receipt.
otito harness . --out .otito/harness.md
{
echo"Use this repo harness to explain the project and suggest the next best engineering task."echocat .otito/harness.md
} | ollama run qwen3:8b --think false --hidethinking --nowordwrap
Local Ollama PR review:
bash
otito pr . --base origin/main --out .otito/pr-review.md
{
echo"Review this PR context. Focus on bugs, missing tests, and risky changes."echocat .otito/pr-review.md
} | ollama run qwen3:8b --think false --hidethinking --nowordwrap
Commands
doctor
Checks the local runtime and optional external tools.
bash
otito doctor --json
install / i
Prints install commands and current binary status. From a local checkout, --global runs npm install -g .; --link runs npm link.
bash
otito install
otito i
otito install --global
otito install --json
Git repositories are scanned through git ls-files --cached --others --exclude-standard so ignored files do not pollute harness context. Plain directories fall back to the built-in walker.
discover <root...>
Discovers repository roots under one or more local directories without indexing them.
By default, search refreshes repo indexes when fingerprints change. Use --offline to read only the stored external indexes.
context <query>
Generates a local context-engine packet for a task. The packet includes inferred intent, primary files, related files, matching tests, implementation patterns, validation commands, conflicts, source evidence, and token estimates.
bash
otito context "add a new MCP tool" --path . --json
otito context "add a new CLI command" --path . --out .otito/context-pack.md
Use this before handing work to a coding agent. It is deterministic and local-first: it relies on repo indexes, code maps, import relationships, tests, and harness commands rather than an external model.
harness <path>
Generates a repo harness with setup commands, validation scripts, runtime scripts, context commands, focus areas, and estimated context-token usage.
The generated workflow runs on pull requests and commit pushes. Pull request runs generate the report, upload an artifact, and create or update a sticky PR comment. Push runs generate and upload the report artifact without commenting.
If code-structure is missing, the command returns an install hint instead of failing mysteriously. If it is not installed globally but npx is available, otito can run it through npx --yes code-structure.
deps <package>
Uses opensrc path <package> to resolve dependency source and optionally search it.
The default output is formatted for terminal reading and ends with estimated token usage. Use --out for the Markdown artifact or --json for structured data.
workspace <repo...>
Generates one product-level report across related repos.
--base <ref>: compare from a specific base ref. Defaults to PR base, upstream, origin/main, or main.
--head <ref>: compare to a specific head ref. Defaults to HEAD.
--number <n>: enrich with gh pr view metadata and review comments.
--github: ask gh to infer the PR from the current branch.
--comment: create or update a sticky GitHub PR comment using gh.
GitHub Actions
This repo includes .github/workflows/otito-ci.yml. The workflow installs dependencies, runs npm run ci, then generates PR or push review context as an uploaded artifact. Use otito init /path/to/target-repo to scaffold an Otito review workflow into another repository.
mcp
Starts a stdio MCP server exposing otito as agent-callable tools. MCP repo-map lookups use an external per-user cache with a file fingerprint, refresh when files change, and never write into the inspected repository.
The server is published in the MCP Registry as io.github.BASHBOP/otito.
bash
otito mcp
When wiring it into an MCP host (Claude Desktop, Claude Code, Codex CLI, Cursor, etc.):
Ollama can provide the local model, but it does not call MCP tools by itself. To use otito through MCP with a local model, use an MCP-capable agent client that supports Ollama as the model provider and configure the otito server above.
Òtítọ́ exposes 13 MCP tools for repository inspection, context, impact, review, and merge evidence.
Tool
Purpose
repo_inspect
Inspect repository shape, scripts, package managers, entrypoints, and git state
repo_map
Compact JSON code map, filterable by domain, kind, and route
Setup, validation, runtime, and context commands for an agent or CI harness
matrix
Prints the tool evaluation matrix for Greploop, code-structure, opensrc, Daytona, and Harnss.
agent-tools
Prints JSON or Markdown metadata derived from the canonical MCP tool catalog, keeping CLI and MCP integrations aligned.
Strategy
Wrap first. Measure pain. Build only the missing pieces.
This keeps the project useful quickly while leaving room to replace weak adapters with owned implementations later.
Part of the toolchain
otito is one of four tools that form a deterministic trust layer for AI-assisted development. Each uses static analysis to answer a question people keep handing to an LLM.
otito (this tool), for context: what does this change actually touch?
tieline, for contracts: did the front end and back end quietly stop agreeing?
bouncer, for compliance: could you defend this to Ofcom?
aiglare, for governance: where can the model do something you can't undo?
