README
¶
confab
Sync and explore Claude Code and Codex sessions. Connect confab to your Confab backend to capture transcripts in real time for exploration, sharing, and analysis.
Your claude and codex workflows stay unchanged.
Install
Supported on macOS and Linux.
curl -fsSL https://raw.githubusercontent.com/ConfabulousDev/confab/main/install.sh | bash
# Follow the instructions to add confab to your PATH
confab setup --backend-url https://confab.yourcompany.com
confab setup detects provider CLIs (claude, codex) on PATH and wires hooks for each. Claude Code and Codex sessions sync in the same setup pass.
Connect to Your Backend
# Initial setup: backend, auth, hooks, bundled skills
confab setup --backend-url https://confab.yourcompany.com
# Login separately (if already set up)
confab login --backend-url https://confab.yourcompany.com
# Check connection and hook status
confab status
# Logout
confab logout
Self-Hosting the Backend
To deploy your own Confab backend, see confab-web.
Usage
Sync Mode (Default)
Sessions are synced incrementally while you work:
# Install sync hooks (done automatically by setup)
confab hooks add
# View running sync daemons
confab sync status
# Remove hooks
confab hooks remove
The sync daemon uploads transcript chunks while you work, reducing data loss if the session exits unexpectedly.
List Sessions
# List all local sessions
confab list
# Filter by duration
confab list -d 5d # Sessions from last 5 days
confab list -d 12h # Sessions from last 12 hours
Use a listed session ID with confab save.
Manual Upload
# Upload specific sessions by ID (use IDs from 'confab list')
confab save abc123de
# Upload multiple sessions
confab save abc123de f9e8d7c6
Redaction
Sensitive data is automatically redacted before uploading. Redaction is enabled by default during confab setup.
Built-in patterns detect common secrets (API keys, private keys, JWT tokens, database passwords, and more) without any configuration.
See Redaction for configuration details.
Codex
Confab supports Codex alongside Claude Code. confab setup detects codex on PATH and wires Codex hooks automatically. Use --provider codex to configure only Codex.
# Auto-detect: installs hooks for every provider CLI on PATH
confab setup --backend-url https://confab.yourcompany.com
# Codex-only (explicit override)
confab setup --provider codex --backend-url https://confab.yourcompany.com
# List Codex sessions
confab list --provider codex
# Upload a specific Codex session
confab save --provider codex <id>
Codex stores rollouts under ~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-*.jsonl. Confab uses Codex's local SQLite state to walk subagent trees and sync descendant rollouts as sidechain files under the root session.
Caveats
- Bundled skills (
/retro) install for both Claude Code and Codex. - GitHub commit/PR linking is wired for Claude Code and Codex. Claude also supports the GitHub MCP PR matcher; Codex uses Bash hooks.
- Codex sync daemons shut down via parent-process liveness, not a
SessionEnd/Stophook.
Configuration
| File | Purpose |
|---|---|
~/.confab/config.json |
Backend URL, API key, and redaction settings |
~/.confab/logs/confab.log |
Operation logs (auto-rotated, 14 day retention) |
Environment Variables
| Variable | Default | Purpose |
|---|---|---|
CONFAB_CLAUDE_DIR |
~/.claude |
Override the Claude Code state directory |
CONFAB_CODEX_DIR |
~/.codex |
Override the Codex state directory |
CONFAB_CONFIG_PATH |
~/.confab/config.json |
Config file location |
CONFAB_LOG_DIR |
~/.confab/logs |
Log directory |
Developer Docs
Each package has a README with extension guides, invariants, and design decisions:
See also CLAUDE.md for AI-oriented architecture notes and development practices.
Development
make build
go test ./...
Building from Source
git clone https://github.com/ConfabulousDev/confab.git
cd confab
make build
./confab install
# Follow the instructions to add confab to your PATH
confab setup --backend-url https://confab.yourcompany.com
License
MIT
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
ABOUTME: General announcement system for post-update feature notifications.
|
ABOUTME: General announcement system for post-update feature notifications. |
|
pkg
|
|
|
codextest
Package codextest provides a reusable Codex SQLite + rollout-files fixture builder for tests across the codebase (pkg/provider, pkg/sync, pkg/daemon, cmd).
|
Package codextest provides a reusable Codex SQLite + rollout-files fixture builder for tests across the codebase (pkg/provider, pkg/sync, pkg/daemon, cmd). |
|
confabpath
Package confabpath builds paths under the user's ~/.confab directory, where all confab local state (config, sync state, inboxes, logs, update timestamps) lives.
|
Package confabpath builds paths under the user's ~/.confab directory, where all confab local state (config, sync state, inboxes, logs, update timestamps) lives. |
|
config
ABOUTME: Manages the /retro bundled skill — install and uninstall.
|
ABOUTME: Manages the /retro bundled skill — install and uninstall. |
|
hookconfig
Package hookconfig owns the install/uninstall/check logic for Confab hooks in Claude Code's settings.json and Codex's config.toml.
|
Package hookconfig owns the install/uninstall/check logic for Confab hooks in Claude Code's settings.json and Codex's config.toml. |
|
loginit
Package loginit wires the logger up to user configuration at process startup.
|
Package loginit wires the logger up to user configuration at process startup. |