README
¶
caic
Coding Agents in Containers. Manage multiple coding agents locally in isolated Docker containers. Access them from your phone with Tailscale. All private.
Installation
curl -fsSL https://caic.xyz/install.sh | bash
From source
go install github.com/caic-xyz/caic/backend/cmd/caic@latest
Documentation
🔥 Full documentation is at docs.caic.xyz 🔥
Contributing
Development requires Node.js 26 and pnpm 12.4.2. See DEV.md.
Made with ❤️ by Marc-Antoine Ruel. Contributions are very appreciated! Thanks in advance! 🙏
Directories
¶
| Path | Synopsis |
|---|---|
|
backend
|
|
|
cmd/caic
command
|
|
|
frontend
Package frontend embeds the built frontend assets and provider logos.
|
Package frontend embeds the built frontend assets and provider logos. |
|
internal/agent
Package agent owns coding-agent sessions, directional history, ordered inputs, and bounded protocol replies.
|
Package agent owns coding-agent sessions, directional history, ordered inputs, and bounded protocol replies. |
|
internal/agent/agenttest
Package agenttest provides shared test helpers and doubles for agent packages.
|
Package agenttest provides shared test helpers and doubles for agent packages. |
|
internal/agent/antigravity
Package antigravity implements agy sessions with conversation-scoped provenance and relay-owned task MCP.
|
Package antigravity implements agy sessions with conversation-scoped provenance and relay-owned task MCP. |
|
internal/agent/backends
Package backends constructs configured agent backend sets.
|
Package backends constructs configured agent backend sets. |
|
internal/agent/claudecode
Package claudecode implements Claude Code sessions with delegation-scoped content, request-correlated answers, controls, and accounting.
|
Package claudecode implements Claude Code sessions with delegation-scoped content, request-correlated answers, controls, and accounting. |
|
internal/agent/codex
Package codex implements app-server transport and shared ordered session metadata and accounting.
|
Package codex implements app-server transport and shared ordered session metadata and accounting. |
|
internal/agent/data/harnesscache
Package harnesscache defines the on-disk per-harness model inventory cache.
|
Package harnesscache defines the on-disk per-harness model inventory cache. |
|
internal/agent/harness
Package harness defines coding agent harness identifiers shared across backend domains.
|
Package harness defines coding agent harness identifiers shared across backend domains. |
|
internal/agent/opencode
Package opencode implements ACP sessions with shared directional metadata and task-scoped MCP.
|
Package opencode implements ACP sessions with shared directional metadata and task-scoped MCP. |
|
internal/agent/pi
Package pi implements Pi RPC sessions with shared native metadata and token accounting.
|
Package pi implements Pi RPC sessions with shared native metadata and token accounting. |
|
internal/agent/relay
Package relay embeds the maintained Python relay used for writable task logs inside containers.
|
Package relay embeds the maintained Python relay used for writable task logs inside containers. |
|
internal/app
Package app assembles the caic backend application.
|
Package app assembles the caic backend application. |
|
internal/app/data
Package data defines the independent app startup settings file schema.
|
Package data defines the independent app startup settings file schema. |
|
internal/auth
Package auth manages caic user sessions and OAuth login identity.
|
Package auth manages caic user sessions and OAuth login identity. |
|
internal/auth/data/v1
Package v1 defines version 1 of the persisted users schema.
|
Package v1 defines version 1 of the persisted users schema. |
|
internal/autoupdate
Package autoupdate provides nightly binary auto-update from GitHub Releases.
|
Package autoupdate provides nightly binary auto-update from GitHub Releases. |
|
internal/bot
Package bot implements forge event-driven task automation: prompt construction, task dispatch via the API, and result comment posting.
|
Package bot implements forge event-driven task automation: prompt construction, task dispatch via the API, and result comment posting. |
|
internal/cmd/check-agent-logs
command
Command check-agent-logs deletes obsolete task logs and validates recent v3 harness records against direction-specific genai wire DTOs.
|
Command check-agent-logs deletes obsolete task logs and validates recent v3 harness records against direction-specific genai wire DTOs. |
|
internal/cmd/gen-api-sdk
command
Project-specific entry point for caic API SDK generation.
|
Project-specific entry point for caic API SDK generation. |
|
internal/cmd/mcp-auth-smoke
command
Smoke-test local MCP OAuth compatibility with shipped MCP clients.
|
Smoke-test local MCP OAuth compatibility with shipped MCP clients. |
|
internal/cmd/record-trace
command
Records complete ordered agent journals through relay.py and validates golden evidence.
|
Records complete ordered agent journals through relay.py and validates golden evidence. |
|
internal/cmd/upnp-dump
command
upnp-dump prints the WAN service and current port mappings reported by a UPnP IGD.
|
upnp-dump prints the WAN service and current port mappings reported by a UPnP IGD. |
|
internal/config/data
Package data defines the independent TOML configuration schema.
|
Package data defines the independent TOML configuration schema. |
|
internal/forge
Package forge defines the interface for interacting with code hosting forges (GitHub, GitLab, etc.) and provides URL parsing and a factory function for selecting the right implementation based on a remote URL.
|
Package forge defines the interface for interacting with code hosting forges (GitHub, GitLab, etc.) and provides URL parsing and a factory function for selecting the right implementation based on a remote URL. |
|
internal/forge/forgecache
Package forgecache provides a persistent cache for CI check-run results from code hosting forges (GitHub, GitLab, etc.).
|
Package forgecache provides a persistent cache for CI check-run results from code hosting forges (GitHub, GitLab, etc.). |
|
internal/forge/forgecache/data
Package data defines the on-disk CI results and notification cache.
|
Package data defines the on-disk CI results and notification cache. |
|
internal/forge/forgemgr
Package forgemgr resolves forge clients for repos, manages per-user rate-limit throttles, and caches GitHub App installation IDs.
|
Package forgemgr resolves forge clients for repos, manages per-user rate-limit throttles, and caches GitHub App installation IDs. |
|
internal/forge/github
Package github implements forge.Forge for github.com using the GitHub REST API.
|
Package github implements forge.Forge for github.com using the GitHub REST API. |
|
internal/forge/gitlab
Package gitlab implements forge.Forge for gitlab.com using the GitLab REST API.
|
Package gitlab implements forge.Forge for gitlab.com using the GitLab REST API. |
|
internal/gittest
Package gittest isolates tests from the Git configuration of the host.
|
Package gittest isolates tests from the Git configuration of the host. |
|
internal/logtest
Package logtest provides lifecycle-safe slog helpers for tests.
|
Package logtest provides lifecycle-safe slog helpers for tests. |
|
internal/preferences
Package preferences manages persistent user preferences with in-memory caching and atomic file persistence.
|
Package preferences manages persistent user preferences with in-memory caching and atomic file persistence. |
|
internal/preferences/data/v1
Package v1 defines version 1 of the persisted user preferences schema.
|
Package v1 defines version 1 of the persisted user preferences schema. |
|
internal/runtime
Package runtime defines caic-owned task execution runtime interfaces and types.
|
Package runtime defines caic-owned task execution runtime interfaces and types. |
|
internal/runtime/runtimetest
Package runtimetest provides shared test doubles for the runtime package's interfaces, reusable by any package that depends on a runtime seam.
|
Package runtimetest provides shared test doubles for the runtime package's interfaces, reusable by any package that depends on a runtime seam. |
|
internal/server
Package server provides the HTTP router serving the API and embedded frontend.
|
Package server provides the HTTP router serving the API and embedded frontend. |
|
internal/server/api
Package api provides shared API infrastructure (errors, validation interface) used across all API versions.
|
Package api provides shared API infrastructure (errors, validation interface) used across all API versions. |
|
internal/server/api/v1
Package v1 defines SSE event types and API data transfer objects for the caic API.
|
Package v1 defines SSE event types and API data transfer objects for the caic API. |
|
internal/server/apiconv
Package apiconv converts backend domain values to API DTOs at the server boundary.
|
Package apiconv converts backend domain values to API DTOs at the server boundary. |
|
internal/server/data/audit
Package audit defines the persisted OAuth and MCP audit event schema.
|
Package audit defines the persisted OAuth and MCP audit event schema. |
|
internal/server/history
Package history incrementally projects raw task records into immutable bodies, section summaries, and pricing observations.
|
Package history incrementally projects raw task records into immutable bodies, section summaries, and pricing observations. |
|
internal/server/history/data
Package data defines the private, rebuildable history pricing journal schema.
|
Package data defines the private, rebuildable history pricing journal schema. |
|
internal/server/ipgeo
Package ipgeo provides IP origin and country allowlist enforcement.
|
Package ipgeo provides IP origin and country allowlist enforcement. |
|
internal/server/ipgeo/data
Package data defines the on-disk named IP-origin cache.
|
Package data defines the on-disk named IP-origin cache. |
|
internal/task
Package task defines task lifecycle values, shared commands, and reusable event folds.
|
Package task defines task lifecycle values, shared commands, and reusable event folds. |
|
internal/task/history/data/headercache/v11
Package v11 defines the independent version 11 task-header cache schema.
|
Package v11 defines the independent version 11 task-header cache schema. |
|
internal/task/taskmgr
Package taskmgr coordinates task execution, pending prompts, attachments, and ordered runtime history import.
|
Package taskmgr coordinates task execution, pending prompts, attachments, and ordered runtime history import. |
|
internal/task/taskrun
Package taskrun orchestrates coding-agent state and ordered conversation and Git history.
|
Package taskrun orchestrates coding-agent state and ordered conversation and Git history. |
|
internal/taskslog
Package taskslog owns physical task-log framing, files, compression, and bounded raw iteration.
|
Package taskslog owns physical task-log framing, files, compression, and bounded raw iteration. |
|
internal/taskslog/data/inputqueue
Package inputqueue defines the durable queued-prompt sidecar schema.
|
Package inputqueue defines the durable queued-prompt sidecar schema. |
|
internal/taskslog/data/v3
Package v3 defines version 3 of caic-owned physical task-log records.
|
Package v3 defines version 3 of caic-owned physical task-log records. |
|
internal/tokens
Package tokens preserves cache-write counts by reported duration with immutable aggregation.
|
Package tokens preserves cache-write counts by reported duration with immutable aggregation. |
|
internal/usage
Package usage provides cached fetchers, task quota tracking, and domain types for LLM provider usage quotas.
|
Package usage provides cached fetchers, task quota tracking, and domain types for LLM provider usage quotas. |
|
internal/usagedb
Package usagedb owns the daily usage rollup over coding-agent task activity.
|
Package usagedb owns the daily usage rollup over coding-agent task activity. |
|
internal/usagedb/data
Package data defines the persisted daily usage and quota row schemas.
|
Package data defines the persisted daily usage and quota row schemas. |
|
Package metrics aggregates numeric measurements of named operations.
|
Package metrics aggregates numeric measurements of named operations. |
|
Package metricsdb manages durable, restart-restored operation metrics.
|
Package metricsdb manages durable, restart-restored operation metrics. |
|
data/v2
Package v2 defines version 2 of the persisted daily metrics log.
|
Package v2 defines version 2 of the persisted daily metrics log. |
Click to show internal directories.
Click to hide internal directories.