Agent Capsule — Development skill for Claude Code

agent-capsule

[![lint][lint-badge]][lint-workflow]

Run a coding agent, [Claude Code](https://code.claude.com/docs) by default, [OpenAI Codex CLI](https://github.com/openai/codex), or [opencode](https://opencode.ai), inside a rootless [Podman](https://podman.io/) container that shares a single project directory with the host.

One shell script, one Dockerfile. The container uses the project's resolved host path as its working directory and also exposes it at `/workspace` for compatibility. It gets an isolated home at `/home/dev`, a Node and Go toolchain, and hard resource limits. Everything else on the host stays out of reach.

What you get

• Rootless containment: container root maps to your host UID, so files written in the project are owned by you. All capabilities dropped, no-new-privileges, memory/CPU/pids limits.
• One login for all sessions: authenticate once per agent with --auth-login (--agent codex --auth-login for Codex); the selected credentials file is live-shared into every session for that agent, token refreshes included.
• Isolated sessions: each project or named session gets its own /home/dev, so parallel agents do not trample each other's transcripts or settings.
• Shared knowledge: one global rules file (~/.agent-capsule/CLAUDE.md) is mounted into every session at the agent's expected path, and Claude's per-project memory is pooled across sessions and linked worktrees of the same repo.
• Tools you list, extensions you turn on: each agent's image holds the CLIs you list in AGENT_CAPSULE_TOOLS, and nobody gets one they did not list. Extensions sit in every image, inert until --with turns them on, so --with never rebuilds.
• Defaults you keep: exported AGENT_CAPSULE_* variables hold your usual add-ons so they are not retyped on every run.

Requirements

• Linux with rootless Podman configured, or macOS with Podman (see