-
Notifications
You must be signed in to change notification settings - Fork 50
Document codedb hook setup #344
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,210 @@ | ||
| # codedb Hooks Labs | ||
|
|
||
| codedb does not have its own hook runtime. It installs an MCP server, and Codex | ||
| or Claude Code can run hooks around MCP tool calls. Use hooks for local policy, | ||
| logging, and guardrails around calls such as `codedb_remote`; do not use them as | ||
| the only security boundary. | ||
|
|
||
| The installer registers the MCP server. Hook configuration is separate because | ||
| hooks execute arbitrary commands with your user permissions. | ||
|
|
||
| ## Lab 1: Codex Hooks | ||
|
|
||
| Enable Codex hooks in `~/.codex/config.toml`: | ||
|
|
||
| ```toml | ||
| [features] | ||
| codex_hooks = true | ||
| ``` | ||
|
|
||
| The codedb MCP registration should look like this: | ||
|
|
||
| ```toml | ||
| [mcp_servers.codedb] | ||
| command = "/Users/you/bin/codedb" | ||
| args = ["mcp"] | ||
| startup_timeout_sec = 30 | ||
| ``` | ||
|
|
||
| Codex discovers hooks next to active config layers: | ||
|
|
||
| - `~/.codex/hooks.json` | ||
| - `~/.codex/config.toml` | ||
| - `<repo>/.codex/hooks.json` | ||
| - `<repo>/.codex/config.toml` | ||
|
|
||
| Project-local hooks load only when the project `.codex/` layer is trusted. | ||
| Matching hooks from multiple files all run. | ||
|
|
||
| ### Guard remote tree calls | ||
|
|
||
| This hook blocks unbounded `codedb_remote action=tree` calls unless the agent | ||
| uses `limit`, `prefix`, or compact summary mode. That keeps huge remote repos | ||
| from dumping too much context. | ||
|
|
||
| `.codex/hooks.json`: | ||
|
|
||
| ```json | ||
| { | ||
| "hooks": { | ||
| "PreToolUse": [ | ||
| { | ||
| "matcher": "mcp__codedb__codedb_remote", | ||
| "hooks": [ | ||
| { | ||
| "type": "command", | ||
| "command": "/usr/bin/env bash \"$(git rev-parse --show-toplevel)/.codex/hooks/codedb_remote_guard.sh\"", | ||
| "timeout": 5, | ||
| "statusMessage": "Checking codedb_remote request" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| `.codex/hooks/codedb_remote_guard.sh`: | ||
|
|
||
| ```bash | ||
| #!/usr/bin/env bash | ||
| set -euo pipefail | ||
|
|
||
| input="$(cat)" | ||
| action="$(printf '%s' "$input" | jq -r '.tool_input.action // empty')" | ||
| limit="$(printf '%s' "$input" | jq -r '.tool_input.limit // empty')" | ||
| prefix="$(printf '%s' "$input" | jq -r '.tool_input.prefix // empty')" | ||
| expand="$(printf '%s' "$input" | jq -r '.tool_input.expand // empty')" | ||
|
|
||
| if [ "$action" = "tree" ] && [ -z "$limit" ] && [ -z "$prefix" ] && [ "$expand" != "false" ]; then | ||
| jq -n '{ | ||
| hookSpecificOutput: { | ||
| hookEventName: "PreToolUse", | ||
| permissionDecision: "deny", | ||
| permissionDecisionReason: "Use codedb_remote tree with expand=false, a prefix, or a limit." | ||
| } | ||
| }' | ||
| fi | ||
| ``` | ||
|
|
||
| Useful Codex hook events for codedb: | ||
|
|
||
| - `PreToolUse`: block or ask before a `mcp__codedb__...` call. | ||
| - `PostToolUse`: summarize or log MCP output after it returns. | ||
| - `PermissionRequest`: decide approval prompts. | ||
| - `UserPromptSubmit`: add repo-specific context before the prompt reaches the model. | ||
| - `Stop`: continue a turn when validation is still missing. | ||
|
|
||
| ## Lab 2: Claude Code Hooks | ||
|
|
||
| Claude Code hook settings live in Claude settings files, while codedb MCP | ||
| registration may live in `~/.claude.json` depending on the installed Claude | ||
| Code version. | ||
|
|
||
| Claude Code's documentation index is published at | ||
| `https://code.claude.com/docs/llms.txt`; use it to discover the current hook | ||
| reference pages before relying on advanced events. | ||
|
|
||
| Common hook locations: | ||
|
|
||
| - `~/.claude/settings.json` | ||
| - `.claude/settings.json` | ||
| - `.claude/settings.local.json` | ||
| - managed policy settings | ||
| - plugin `hooks/hooks.json` | ||
| - skill or agent frontmatter | ||
|
|
||
| Claude Code MCP tool names use the same `mcp__<server>__<tool>` shape, so | ||
| codedb tools match as `mcp__codedb__codedb_remote`, | ||
| `mcp__codedb__codedb_search`, or `mcp__codedb__.*`. | ||
|
|
||
| `.claude/settings.json`: | ||
|
|
||
| ```json | ||
| { | ||
| "hooks": { | ||
| "PreToolUse": [ | ||
| { | ||
| "matcher": "mcp__codedb__codedb_remote", | ||
| "hooks": [ | ||
| { | ||
| "type": "command", | ||
| "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/codedb_remote_guard.sh", | ||
| "timeout": 5, | ||
| "statusMessage": "Checking codedb_remote request" | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "PostToolUse": [ | ||
| { | ||
| "matcher": "mcp__codedb__.*", | ||
| "hooks": [ | ||
| { | ||
| "type": "command", | ||
| "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log_codedb_tool.sh", | ||
| "async": true, | ||
| "timeout": 30 | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The same `codedb_remote_guard.sh` script from the Codex lab works for Claude | ||
| Code because both clients pass MCP tool input as JSON and accept | ||
| `hookSpecificOutput.permissionDecision`. | ||
|
|
||
| `.claude/hooks/log_codedb_tool.sh`: | ||
|
|
||
| ```bash | ||
| #!/usr/bin/env bash | ||
| set -euo pipefail | ||
|
|
||
| input="$(cat)" | ||
| tool="$(printf '%s' "$input" | jq -r '.tool_name // "unknown"')" | ||
| event="$(printf '%s' "$input" | jq -r '.hook_event_name // "unknown"')" | ||
| repo="$(printf '%s' "$input" | jq -r '.tool_input.repo // empty')" | ||
| action="$(printf '%s' "$input" | jq -r '.tool_input.action // empty')" | ||
|
|
||
| mkdir -p .claude/logs | ||
| printf '%s\t%s\t%s\t%s\n' "$event" "$tool" "$repo" "$action" >> .claude/logs/codedb-tools.tsv | ||
| ``` | ||
|
|
||
| Claude Code has more hook events and handler types than Codex. The ones most | ||
| useful for codedb are: | ||
|
|
||
| - `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` for MCP tool policy and telemetry. | ||
| - `PostToolBatch` when the next model call needs context from a full batch of tools. | ||
| - `UserPromptSubmit` and `UserPromptExpansion` for prompt-time repo context. | ||
| - `Stop` or `SubagentStop` for validation gates before an agent finishes. | ||
| - `ConfigChange`, `CwdChanged`, and `FileChanged` for environment reloads. | ||
|
|
||
| Claude Code also supports command, HTTP, MCP-tool, prompt, and agent hook | ||
| handlers. Prefer command hooks for deterministic policy checks; use async | ||
| command hooks for logging that should not block the agent loop. | ||
|
|
||
| ## codedb_remote Defaults | ||
|
|
||
| `codedb_remote` always calls `https://api.wiki.codes`. The old `codegraff` | ||
| backend name is no longer a supported route. Keep `backend="wiki"` only for | ||
| compatibility with older prompts, or omit `backend` entirely. | ||
|
|
||
| Start with: | ||
|
|
||
| ```text | ||
| codedb_remote repo="openai/codex" action="actions" | ||
| codedb_remote repo="openai/codex" action="tree" expand=false | ||
| codedb_remote repo="openai/codex" action="tree" prefix="codex-rs/" limit=100 | ||
| codedb_remote repo="openai/codex" action="read" path="codex-rs/core/src/codex.rs" lines="1-80" | ||
| ``` | ||
|
|
||
| Use `scope="runtime"` for user-facing dependency risk and `scope="all"` when | ||
| you also need dev and tooling dependencies: | ||
|
|
||
| ```text | ||
| codedb_remote repo="vercel/next.js" action="score" scope="runtime" | ||
| codedb_remote repo="vercel/next.js" action="cves" scope="all" | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The installer computes
versiondynamically, but this note hard-codesrelease/0.2.579for the hook examples. As soon as users install a newer release, the printed URL can become stale (or disappear), so the setup guidance no longer matches the binary they just installed. Please derive this link from$version(or use a stable docs URL); the same hard-coded line is mirrored in the website installer copies.Useful? React with 👍 / 👎.