Verified, bounded repository context for AI coding tools.
Get started · How it works · Dashboard · Compatibility · Security · Roadmap
Impresari Context turns an exact local repository snapshot into bounded, task-specific context packets with recoverable source evidence, explicit omissions, integrity checks, and freshness validation.
It works beneath existing coding agents without taking control of execution, permissions, approvals, or business policy. The result is a neutral context layer that clients can inspect, verify, and integrate without replacing their existing workflow.
| Bounded by design | Verifiable evidence | Local-first | Client-neutral |
|---|---|---|---|
| Explicit byte, item, depth, and time ceilings | Exact source spans, digests, omissions, and freshness | Repository content and audit state stay local | One core serves CLI, MCP, and recorded client integrations |
| Scope | Current state |
|---|---|
| Published release | v0.1.0 provides the portable CLI and local stdio MCP baseline for macOS ARM64, Linux x86-64, and Windows x86-64. Its exact claims are defined by the v0.1.0 conformance statement. |
Current main |
Roadmap Phases 0–5 are complete for their accepted scopes. The branch adds deterministic planning, expanded bounded structural evidence, five version-bound first-class client integrations, quickstart, and the local dashboard with narrowing-only budget controls. |
| Still gated | Cross-platform production analyzer confinement, YARA-X repository scanning, Homebrew distribution, automatic updates, and the independent human security review are not published capabilities. Exact Linux candidates and synthetic YARA-X work do not authorize production scanning. |
Capabilities on main must not be attributed retroactively to the v0.1.0
binaries. See the roadmap and
compatibility matrix for current,
version-bound evidence and non-claims.
Download the archives and checksums from the
v0.1.0 release,
or use the checksum-verifying installer on macOS ARM64 or Linux x86-64. Download
and inspect the installer before running it:
curl --fail --location --output impresari-install.sh \
https://raw.githubusercontent.com/tdloB/impresari-context/main/scripts/install.sh
less impresari-install.sh
sh impresari-install.sh --version v0.1.0
The installer never selects latest, changes shell startup files, or
overwrites an installed binary. Other published platforms can use the release
archives directly.
git clone https://github.com/tdloB/impresari-context.git
cd impresari-context
cargo build --workspace --locked
./scripts/check.sh
The current source pins Rust 1.98.0 and declares Rust 1.96 as its minimum supported Rust version.
quickstart is available on main and is not present in v0.1.0:
impresari-context quickstart \
<codex|claude|cursor|copilot|vscode> \
<absolute-workspace> \
<absolute-separate-cache> \
<absolute-client-config>
The command previews a machine-readable receipt by default. Review it, then
repeat the command with --apply. It does not trust, start, sign in to, enable,
approve, or invoke the client. See the
local MCP connection guides
for the exact configuration path and recorded scope for each client.
flowchart LR
A[Authorized repository snapshot] --> B[Bounded retrieval and structural evidence]
B --> C[Deterministic planner and budget policy]
C --> D[Immutable context packet]
D --> E[AI coding client]
B -. source-free audit metadata .-> F[Local audit and policy state]
F --> G[Loopback dashboard]
Every request starts from an explicit workspace and a separate cache root. Packets retain the evidence needed to recover exact current source and report unsupported, partial, omitted, unresolved, stale, and truncated states rather than silently broadening a claim.
| Capability | What it provides |
|---|---|
| Evidence engine | Capability-scoped reads, deterministic snapshots, bounded exact-path, filename, literal, and lexical retrieval, byte-verifiable evidence, immutable packets, validation, and no-overwrite export. |
| Structural context | Pinned parser workers and snapshot-bound structural graphs with explicit unresolved and truncated states. Syntax evidence never implies compiler, runtime, package-manager, or language-server semantics. |
| Deterministic planning | Profile-bound plans for orientation, implementation, bug investigation, change review, security review, test selection, and configuration changes, including coverage and omission reporting. |
| Local MCP | A single-client, process-local stdio transport with fixed launch authority. It adds no HTTP listener, network, model, source-write, approval, execution, or orchestration capability. |
| Client integrations | Managed connection, native guidance, guided delivery, and lifecycle-health evidence are admitted independently for exact client, version, OS, and configuration scopes. |
The post-v0.1.0 dashboard is a foreground, loopback-only view of validated
audit metadata and exact-owned budget-policy state:
impresari-context dashboard serve <audit-cache-root> <policy-state-root>
It shows request activity and narrowing-only budget policy without displaying repository source or context packets. It does not open a browser, create a daemon, make outbound requests, or raise a governing limit. Policy changes are preview-first and bound to the exact current state.
Source-free synthetic DBC-4 fixture. The dashboard displays local audit metadata—not repository source or packet contents. See the native-browser admission record.
| Client | Classification on current main |
|---|---|
| Codex | First-class, with separately recorded L1–L4 evidence |
| Claude Code | First-class, with separately recorded L1–L4 evidence |
| Cursor | First-class, with separately recorded L1–L4 evidence |
| GitHub Copilot CLI | First-class, with separately recorded L1–L4 evidence |
| VS Code Copilot | First-class, with separately recorded L1–L4 evidence |
| Gemini CLI | Generic local MCP compatibility only |
“First-class” means a maintained versioned connection kit and client-specific end-to-end evidence. It is not a claim about every version or platform. Consult the compatibility matrix for exact versions, operating systems, lifecycle levels, expiry, and limitations.
Current main has bounded syntax-derived structural evidence for:
- Languages: TypeScript, JavaScript, Python, Java, Kotlin, C#, Scala, Elixir, Clojure, Haskell, Go, Rust, C, C++, Ruby, PHP, and Swift.
- Configuration formats: strict JSON, JSONC, TOML, and deliberately bounded YAML.
File discovery and lexical evidence are broader than structural support. The compatibility matrix defines the exact distinction and every format limitation.
| Impresari Context is | Impresari Context is not |
|---|---|
| A bounded evidence and context-packet layer | An agent orchestrator or autonomous development runtime |
| A local CLI and stdio MCP process | A remote MCP service, daemon, or hosted source repository |
| A deterministic planner with explicit omissions | A guarantee of deterministic model behavior or tool selection |
| A narrowing-only local budget-control surface | A billing system or authority to increase organizational limits |
| A foundation for separately gated security analysis | A production malware scanner, quarantine VM, or universal sandbox today |
The trusted core is designed to fail closed on traversal, symlinks, stale evidence, integrity failures, incompatible contracts, over-budget operations, and authority-expanding input.
Current main also includes evidence-only hostile-repository inventory,
synthetic analyzer normalization, application-enforced synthetic worker
supervision, exact-host isolation candidates, and staged YARA-X compatibility
work. These do not establish that a repository is safe or malware-free and
do not authorize production scanner execution. macOS, Linux, and Windows
confinement are admitted independently; there is no blanket cross-platform
sandbox claim.
Read the security threat model, Step 1 limitations, and security policy before relying on a security-sensitive capability. Suspected vulnerabilities belong in the private security advisory channel, not a public issue.
Reproducible comparisons against native client workflows are under development in the independent evaluation harness. Published results will identify the exact repository snapshot, client, model, configuration, baseline, run count, and observed range.
Until those results exist, this README makes no token-savings, quality, or productivity claim. The approved measurement contract is documented in the evaluation and benchmark PRD.
| Area | Start here |
|---|---|
| Using Impresari | CLI and MCP interfaces · Local MCP connection guides · Compatibility matrix |
| Architecture | Architecture · System boundaries · Resource policy |
| Product direction | Master PRD · Revised roadmap · Client integration roadmap |
| Security | Threat model · Residual risks · Independent review guide |
| Decisions and evidence | ADR index · Verification records · Influences and provenance |
| Release assurance | v0.1.0 conformance · Release evidence · Changelog |
Use GitHub Issues for bugs and feature requests. Read CONTRIBUTING.md and the Code of Conduct before proposing a change.
Impresari Context is licensed under Apache License 2.0. Contributions require Developer Certificate of Origin 1.1 sign-off as described in CONTRIBUTING.md.