README
¶
Overgent
Overgent is air traffic control for multiple coding agents working in one repository. It catches overlapping edits, stale contract assumptions, and duplicated work while agents are working—not at merge time. It observes and routes coordination context; it never edits code, merges changes, or steers an agent's model loop, tools, or permissions.
Install
macOS and Linux:
curl -fsSL https://overgent.com/install.sh | sh
Windows, in PowerShell:
irm https://overgent.com/install.ps1 | iex
The installer verifies the signed release manifest, the archive hash, and the executable signature before it changes anything. Desktop applications are at overgent.com.
| Platform | Status |
|---|---|
| macOS 12+, Apple silicon | Qualified on real hardware |
| Linux x86-64 | Builds and passes its tests in CI; not yet run on a Linux desktop by us |
| Windows 10 1809+, x86-64 | Builds and type-checks in CI; not yet run on a Windows machine by us |
Linux and Windows support is complete but unqualified: the code is there and tested, and we have not yet sat in front of either. Please report what breaks. For anything else, build from source.
Local by default
A new Project runs against the bundled backend on loopback. Nothing leaves your Mac, and its coordination data stays under your Overgent profile root.
overgent init --local
overgent status
Team mode
Create or join a team Project on Overgent Cloud when you want to work with teammates. Only derived, structured coordination facts sync; source files, raw diffs, Git objects, transcripts, prompts, credentials, and command output do not. See the full prohibited-data list.
You can also run the same backend yourself; see self-hosting.
Terminal experience
Run overgent inside a registered repository for a contextual status, or use
overgent projects outside one. overgent init provides guided setup on a
terminal and requires explicit flags in scripts. Human output is used on a
terminal; read commands expose versioned JSON with --json.
overgent help
overgent privacy
overgent completion zsh > ~/.zfunc/_overgent
The CLI remains a companion to the Project workroom, not a coding-agent shell. See the CLI experience contract.
Bring your own model
Configure semantic judgment for a Project with your own provider key:
export ANTHROPIC_API_KEY='...'
overgent ai set --judgment-provider anthropic --judgment-model claude-sonnet-4-5 --judgment-key-env ANTHROPIC_API_KEY
overgent ai status --json
See AI providers for Project settings, OpenAI-compatible providers, and how Overgent behaves with no key configured.
Agents and findings
Codex and Claude Code are supported today. Cursor has a configuration adapter, but its live hook behavior is not yet verified. To add another agent adapter, follow adapter development.
Deterministic findings are always available: path overlap, shared dependencies, and contract evidence. Semantic findings are available only when a provider is configured, and remain explicitly probabilistic.
Development
Read the documentation in order, then use these checks:
go test ./...
go vet ./...
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
pnpm protocol:generate
pnpm protocol:check
See contributing and security reporting. Overgent is licensed under Apache-2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
fake-producer
command
Command fake-producer emits one synthetic event for contract and demo fixtures.
|
Command fake-producer emits one synthetic event for contract and demo fixtures. |
|
overgent
command
|
|
|
release-keygen
command
Command release-keygen creates the offline Ed25519 trust anchor used to sign Overgent update metadata.
|
Command release-keygen creates the offline Ed25519 trust anchor used to sign Overgent update metadata. |
|
release-metadata
command
Command release-metadata creates the small signed manifest consumed by the updater.
|
Command release-metadata creates the small signed manifest consumed by the updater. |
|
internal
|
|
|
activation
Package activation moves a single-use dashboard ticket from the CLI to the hosted API through the member's own browser.
|
Package activation moves a single-use dashboard ticket from the CLI to the hosted API through the member's own browser. |
|
adapterrepair
Package adapterrepair adopts agent bindings that an earlier Overgent left behind on this Mac.
|
Package adapterrepair adopts agent bindings that an earlier Overgent left behind on this Mac. |
|
auth
Package auth owns local credential boundaries and redacted authentication values.
|
Package auth owns local credential boundaries and redacted authentication values. |
|
cliui
Package cliui contains the terminal-facing presentation primitives shared by Overgent commands.
|
Package cliui contains the terminal-facing presentation primitives shared by Overgent commands. |
|
codexappserver
Package codexappserver speaks the Codex app-server JSON-RPC protocol to a private stdio child process.
|
Package codexappserver speaks the Codex app-server JSON-RPC protocol to a private stdio child process. |
|
contract
Package contract derives per-file API-surface fingerprints for the paths the manifest pipeline already observes (ADR-044, ADR-048).
|
Package contract derives per-file API-surface fingerprints for the paths the manifest pipeline already observes (ADR-044, ADR-048). |
|
contract/fingerprint
Package fingerprint holds the contract-fingerprint value types and their bounds.
|
Package fingerprint holds the contract-fingerprint value types and their bounds. |
|
contract/multilang
Package multilang is the spike's tree-sitter-backed contract extractor.
|
Package multilang is the spike's tree-sitter-backed contract extractor. |
|
contract/tsw
Package tsw runs a tree-sitter build compiled to wasm32-wasi under wazero.
|
Package tsw runs a tree-sitter build compiled to wasm32-wasi under wazero. |
|
contract/wasmgrammar
Package wasmgrammar carries the built tree-sitter modules as embedded blobs, one per language.
|
Package wasmgrammar carries the built tree-sitter modules as embedded blobs, one per language. |
|
credential
Package credential stores Overgent's secrets in the operating system's own credential store: the hosted device credential, and the local backend's instance secret and deployment secrets key (docs/security-privacy.md, "Local").
|
Package credential stores Overgent's secrets in the operating system's own credential store: the hosted device credential, and the local backend's instance secret and deployment secrets key (docs/security-privacy.md, "Local"). |
|
cursorsetup
Package cursorsetup installs, inspects, moves, and removes Overgent's managed hooks in a Cursor project.
|
Package cursorsetup installs, inspects, moves, and removes Overgent's managed hooks in a Cursor project. |
|
events
Package events constructs and queues versioned protocol events.
|
Package events constructs and queues versioned protocol events. |
|
localbackend
Package localbackend supervises the open-source Convex backend that a local-mode Project runs on loopback.
|
Package localbackend supervises the open-source Convex backend that a local-mode Project runs on loopback. |
|
logging
Package logging defines privacy-safe logging composition shared by local modes.
|
Package logging defines privacy-safe logging composition shared by local modes. |
|
mcp
Package mcp exposes lifecycle tools while leaving coding-agent control external.
|
Package mcp exposes lifecycle tools while leaving coding-agent control external. |
|
platform
Package platform contains narrow, fail-closed operating-system adapters.
|
Package platform contains narrow, fail-closed operating-system adapters. |
|
service
Package service manages the current user's Overgent background service.
|
Package service manages the current user's Overgent background service. |
|
sessiontranscript
Package sessiontranscript reads the vendor session record for an agent session so a member can see their own work (ADR-036).
|
Package sessiontranscript reads the vendor session record for an agent session so a member can see their own work (ADR-036). |
|
sync
Package sync publishes through the versioned Overgent HTTP contract.
|
Package sync publishes through the versioned Overgent HTTP contract. |
|
update
Package update verifies signed release metadata and performs recoverable executable replacement.
|
Package update verifies signed release metadata and performs recoverable executable replacement. |
|
protocol
|
|
|
generated/go
Package protocoltypes provides primitives to interact with the openapi HTTP API.
|
Package protocoltypes provides primitives to interact with the openapi HTTP API. |
|
Command generate-brand-icons renders the canonical Overgent app icon SVG's geometry into the PNG sizes required by Apple's iconutil.
|
Command generate-brand-icons renders the canonical Overgent app icon SVG's geometry into the PNG sizes required by Apple's iconutil. |
|
validation
|
|
|
evals/coordination
command
|
|