agent-context-bridge

Architecture

Agent Context Bridge is a local-first TypeScript ESM project. The core design is adapter-driven: agent-specific parsers normalize local session records into a shared event model, and renderers turn those events into concise target-agent handoff packets.

Design Principles

Local-first: runtime state stays in the current project under .agent-bridge/.
Evidence-backed: handoff packets include raw evidence references instead of embedding complete transcripts.
Default-deny: remote sync and native writes require explicit policy checks and user intent.
Adapter isolation: each agent parser handles its own session shape and preserves unknown records conservatively.
Shared surfaces: CLI, MCP, and UI commands call the same underlying services.

Main Modules

Area	Responsibility
`src/adapters/`	Agent-specific session detection and parsing.
`src/agents/`	Built-in agent definitions, aliases, and adapter registry.
`src/events/`	Timeline and search over normalized events.
`src/renderers/`	Target-specific handoff rendering.
`src/registry/`	Local capability mapping packs and negotiation.
`src/protocol/`	Protocol descriptor and agent compatibility reports.
`src/policy/`	Default-deny policy evaluation.
`src/remote/`	Encrypted local-directory sync bundles.
`src/team/`	Hash-chained team ledger.
`src/collab/`	Project-local collaboration session state.
`src/integrations/`	Low-coupling integrations such as CC Switch.
`src/ui/`	Small local browser UI backed by the same services.

Data Flow

bridge detect creates project-local storage and default registry mappings.
Agent adapters detect nearby native session files.
Parsers convert native records into normalized events with raw_ref pointers.
Timeline, search, registry, protocol, and policy services operate on normalized data.
Renderers produce target-agent handoff packets under .agent-bridge/packets/.
CLI, MCP, CC Switch, and UI surfaces expose the same workflow.

Safety Boundaries

.agent-bridge/ is runtime state and should not be committed.
Full raw transcripts are not included in handoff packets by default.
Native hook installation is explicit and writes project-local manifests.
Remote sync writes encrypted bundles only to explicit local paths.
Pull/push operations require policy enablement, key material, and confirmation.

This site is open source. Improve this page.