Deployment & Setup
Relevant source files
The following files were used as context for generating this wiki page:
oboete is a lightweight, single-binary memory system for coding agents that captures session data, curates knowledge, and provides context for new sessions. Setup involves wiring the oboete binary into various agent hooks and Model Context Protocol (MCP) server configurations to ensure seamless data capture and memory retrieval.
Sources: CLAUDE.md:3, src/main.rs:4-6
Supported Agents
oboete provides automated setup for several coding agents. The system wires lifecycle hooks and MCP registrations to capture events such as session starts, user prompts, and tool usage.
| Agent | Configuration Method | Default Hook Files |
|---|---|---|
| Claude | CLI/JSON | ~/.claude/settings.json, .claude.json |
| Codex | JSON/TOML | ~/.codex/hooks.json, config.toml |
| Grok | JSON/TOML | ~/.grok/hooks/oboete.json, config.toml |
| agy | JSON | ~/.gemini/config/hooks.json, mcp_config.json |
| OpenCode | JS/JSON | plugins/oboete.js, opencode.json |
| pi | TS | extensions/oboete.ts |
| Cursor | JSON | hooks.json, mcp.json |
Sources: src/setup.rs:18, src/setup.rs:105-144
Core Setup Architecture
The setup process uses a HookCommand structure to generate absolute paths and arguments for the binary. This ensures that hooks run correctly regardless of the agent's working directory.
The diagram shows the logical flow of the setup command, emphasizing executable localization and atomic file updates.
Sources: src/setup.rs:52-80, src/setup.rs:152-166
Automated Hook Wiring
The command oboete setup <agent> automatically modifies agent configuration files. For most agents, this includes registering specific events and timeouts.
Hook Commands and Events
Hooks are commands formatted as: <path/to/oboete> [--home <dir>] hook <agent> <event>. The system monitors the following event types:
- SessionStart: Triggered when a new agent session begins.
- UserPromptSubmit: Captured when a user sends a prompt.
- PostToolUse / PostToolUseFailure: Captured after an agent uses a tool.
- Stop: Captured when an agent finishes its response.
- SessionEnd: Triggered when a session is closed.
Sources: src/setup.rs:25-50, src/setup.rs:175-179
Implementation Details
Setup uses atomic writes to prevent file corruption. It creates a temporary file next to the target, writes the full content, and performs a rename operation. If a file was previously owned by the developer, oboete leaves a .oboete.bak copy.
Sources: src/setup.rs:11-13, src/setup.rs:299-310
Provider Configuration & Keys
oboete uses external AI providers for memory curation and summarization. These are configured in config.toml.
API Keys
API keys are never stored directly in the main configuration. They must be placed in specific files following the pattern ~/<NAME>_KEY.md, with the token on the second line. oboete ensures these keys are never printed to logs or passed to subprocess environments.
Sources: CLAUDE.md:21-22, src/provider.rs:364-367
Environment Variables
Setup and runtime behavior can be influenced by several environment variables:
OBOETE_HOME: Overrides the default data directory (~/.oboete).OBOETE_SKIP: If set to1, the hook ignores the current session.OBOETE_REPLAY: Used during testing to identify sampled events.OBOETE_FIELD_CAP: Limits the size of stored strings (default 64 KB).
Sources: CLAUDE.md:24, src/main.rs:43, src/capture.rs:21-44
System Verification
The oboete doctor command provides a comprehensive report on the deployment state. It validates:
- Hook Wiring: Checks if agent configuration files point to the correct oboete binary.
- Database Health: Reports sizes for
oboete.db,knowledge.db, andproviders.db. - Provider Readiness: Checks API key availability and current budget status.
- Storage Space: Warns if free disk space is below 100 MB.
Sources: src/setup.rs:722-740, src/setup.rs:885-920
The sequence diagram illustrates the diagnostic checks performed by the doctor command to ensure the system is operational.
Sources: src/setup.rs:722-880
Conclusion
Setting up oboete requires a one-time execution of the setup command for relevant agents and the configuration of AI providers. The system prioritizes safety through atomic file operations and strict API key isolation, while the doctor utility ensures ongoing operational visibility.
Sources: src/setup.rs:920-925, CLAUDE.md:21-22