codexkit 1.0.0

package/.codex/hooks/after_agent.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -euo pipefail
+# Hook: after_agent
+# Runs after each agent turn. Appends a lightweight breadcrumb to the worklog only.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+if [[ -x "$SCRIPT_DIR/scripts/append_worklog.sh" ]]; then
+  "$SCRIPT_DIR/scripts/append_worklog.sh" "Agent turn completed at $TIMESTAMP"
+fi

package/.codex/hooks/after_tool_use.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+# Hook: after_tool_use
+# Runs after each tool use. Detects file changes for lightweight operator awareness.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if [[ -x "$SCRIPT_DIR/scripts/detect_changed_files.sh" ]]; then
+  "$SCRIPT_DIR/scripts/detect_changed_files.sh"
+fi

package/.codex/hooks/post_commit.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+# Hook: post_commit
+# Appends a short checkpoint after a successful commit hook invocation.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if [[ -x "$SCRIPT_DIR/scripts/append_worklog.sh" ]]; then
+  "$SCRIPT_DIR/scripts/append_worklog.sh" "Commit lifecycle hook completed"
+fi

package/.codex/hooks/pre_commit.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -euo pipefail
+# Hook: pre_commit
+# Lightweight placeholder for future commit-time checks.
+
+exit 0

package/.codex/hooks/session_start.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+set -euo pipefail
+# Utility: session_start
+# Builds a startup brief into context/session-context.md.
+# This script is a workflow helper, not a native Codex hook event.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUTPUT_FILE="$SCRIPT_DIR/context/session-context.md"
+
+mkdir -p "$SCRIPT_DIR/context"
+
+if [[ -x "$SCRIPT_DIR/scripts/build_startup_brief.sh" ]]; then
+  {
+    echo "# Session Context"
+    echo ""
+    "$SCRIPT_DIR/scripts/build_startup_brief.sh"
+  } > "$OUTPUT_FILE"
+fi

package/.codex/hooks/stop.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+# Hook: stop
+# Captures a lightweight end-of-session marker.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if [[ -x "$SCRIPT_DIR/scripts/append_worklog.sh" ]]; then
+  "$SCRIPT_DIR/scripts/append_worklog.sh" "Session stop hook completed"
+fi

package/.codex/mcp/README.md

@@ -0,0 +1,143 @@
+# MCP Server Configuration
+
+## What is MCP?
+
+**Model Context Protocol (MCP)** is an open protocol that allows AI agents to connect to external tools and services. MCP servers provide capabilities like documentation lookup, web search, code navigation, and more.
+
+## Two-Tier Configuration
+
+Codex CLI merges **user-level** and **project-level** configs. To avoid conflicts:
+
+| Level       | File                   | Use for                                               |
+| ----------- | ---------------------- | ----------------------------------------------------- |
+| **User**    | `~/.codex/config.toml` | MCPs you use across all projects (context7, exa, ref) |
+| **Project** | `.codex/config.toml`   | MCPs specific to this project (tilth)                 |
+
+> **Important:** If the same MCP server name appears in both files with different transport types (HTTP vs stdio), Codex CLI fails with a merge conflict. Always configure user-level MCPs in `~/.codex/config.toml`.
+> **Secrets:** keep API keys in `.codex/.env` and launch with `codexkit run`. Do not hardcode secrets in either config file.
+
+## Project-Level MCP (already configured)
+
+**Tilth** is included in `.codex/config.toml` and works immediately — no API key needed.
+
+| Server | Tools                                                                   | Key Required |
+| ------ | ----------------------------------------------------------------------- | ------------ |
+| Tilth  | `tilth_search`, `tilth_read`, `tilth_files`, `tilth_edit`, `tilth_deps` | No           |
+
+## User-Level MCPs (add to ~/.codex/config.toml)
+
+Copy the relevant blocks below into your `~/.codex/config.toml`.
+See `*.toml.example` files in this directory for annotated versions.
+From the target project, create `.codex/.env` from `.codex/.env.example` and launch Codex with `codexkit run`.
+
+> **All three MCPs are primary.** They run in parallel for best results.
+> Without them, research is limited to codebase inspection and grepsearch.
+
+### Context7 — Library API docs (Primary)
+
+**Primary** for precise library API lookups — function signatures, code examples, version-specific docs. Deepest coverage for known libraries.
+
+```toml
+[mcp_servers.context7]
+url = "https://mcp.context7.com/mcp"
+env_http_headers = { "CONTEXT7_API_KEY" = "CONTEXT7_API_KEY" }
+startup_timeout_ms = 20_000
+```
+
+Get your key at [context7.com](https://context7.com) → Dashboard.
+
+### Ref — Documentation search (Primary)
+
+**Primary** for broad documentation search — covers official docs, private repos, and PDFs. Has a credit system. Broadest documentation coverage.
+
+```toml
+[mcp_servers.ref]
+command = "npx"
+args = ["-y", "ref-tools-mcp@latest"]
+env_vars = ["REF_API_KEY"]
+```
+
+Get your key at [ref.tools](https://ref.tools) → Dashboard.
+
+### Exa — Web search & code context (Primary)
+
+**Primary** for web research and code context. Most versatile tool — handles general web search (`exa_web_search_exa`) and programming-specific code context (`exa_get_code_context_exa`).
+
+```toml
+[mcp_servers.exa]
+url = "https://mcp.exa.ai/mcp"
+bearer_token_env_var = "EXA_API_KEY"
+```
+
+Get your key at [exa.ai](https://exa.ai) → Dashboard.
+
+### Optional: Basic Memory — real long-term memory
+
+Use this only if you need searchable or semantic memory beyond repo notes.
+Codexkit's default `.codex/context/` and `.codex/memory/` directories still
+remain the repo-visible source of truth.
+
+```toml
+[mcp_servers.basic-memory]
+url = "https://cloud.basicmemory.com/mcp"
+bearer_token_env_var = "BASIC_MEMORY_API_KEY"
+```
+
+See `basic-memory.toml.example` for the annotated version and
+[`docs/memory-mcp.md`](/Users/mac/Desktop/Workspace/codexkit/docs/memory-mcp.md)
+for setup guidance and layering advice.
+
+### Optional: Custom Memory Bridge
+
+If your team uses a different MCP memory service, keep it additive and user-level by default.
+Codexkit ships a generic example in `memory-bridge.toml.example` for both HTTP and stdio patterns.
+
+Rules:
+- keep secret-bearing or user-specific memory servers in `~/.codex/config.toml`
+- do not treat external memory as the only home for decisions, blockers, or conventions
+- sync durable conclusions back into `.codex/context/` or `.codex/memory/`
+
+## Agent → MCP Tool Mapping
+
+| Agent    | Primary Tools              | Built-in Tools              |
+| -------- | -------------------------- | --------------------------- |
+| Scout    | exa, ref, context7         | grepsearch, tilth           |
+| Explorer | tilth                      | grep, file reads            |
+| Builder  | tilth                      | grep, file reads            |
+| Planner  | tilth, ref, context7       | grep, file reads, exa       |
+| Reviewer | tilth                      | grep, file reads            |
+
+### Fallback Chain (when a tool is unavailable)
+
+All three run together by default. Fallback only when a tool is not configured or fails.
+
+```
+All available:     exa + ref + context7 (parallel) → merge results
+ref unavailable:   exa + context7
+context7 unavail:  exa + ref
+exa unavailable:   ref + context7 + grepsearch
+Only one:          use it + grepsearch
+None available:    grepsearch + tilth only (report limitation)
+Codebase:          tilth → grep + file reads (always)
+```
+
+## Adding Custom MCP Servers
+
+Add a `[mcp_servers.<name>]` block to either config file:
+
+**Stdio transport** (local process):
+
+```toml
+[mcp_servers.my-server]
+command = "npx"
+args = ["-y", "my-mcp-package"]
+```
+
+**HTTP transport** (remote service):
+
+```toml
+[mcp_servers.my-server]
+url = "https://example.com/mcp"
+```
+
+Refer to the [MCP specification](https://modelcontextprotocol.io/) for details on building your own MCP servers.

package/.codex/mcp/basic-memory.toml.example

@@ -0,0 +1,10 @@
+[mcp_servers.basic-memory]
+# Basic Memory Cloud MCP endpoint
+url = "https://cloud.basicmemory.com/mcp"
+
+# Export this in your shell profile, then restart Codex:
+# export BASIC_MEMORY_API_KEY=your-api-key
+bearer_token_env_var = "BASIC_MEMORY_API_KEY"
+
+# Optional: increase startup timeout if your network is slow
+# startup_timeout_ms = 20_000

package/.codex/mcp/context7.toml.example

@@ -0,0 +1,13 @@
+# Context7 — Library documentation search
+# Provides: context7_resolve-library-id, context7_query-docs
+# Requires: CONTEXT7_API_KEY (get from https://context7.com → Dashboard)
+#
+# Keep the key in your shell or .codex/.env, then launch Codex with:
+#   codexkit run
+#
+# Add this to ~/.codex/config.toml (NOT project-level config):
+
+[mcp_servers.context7]
+url = "https://mcp.context7.com/mcp"
+env_http_headers = { "CONTEXT7_API_KEY" = "CONTEXT7_API_KEY" }
+startup_timeout_ms = 20_000

package/.codex/mcp/exa.toml.example

@@ -0,0 +1,12 @@
+# Exa — Web search and code context
+# Provides: exa_web_search_exa, exa_get_code_context_exa
+# Requires: EXA_API_KEY (get from https://exa.ai → Dashboard)
+#
+# Keep the key in your shell or .codex/.env, then launch Codex with:
+#   codexkit run
+#
+# Add this to ~/.codex/config.toml (NOT project-level config):
+
+[mcp_servers.exa]
+url = "https://mcp.exa.ai/mcp"
+bearer_token_env_var = "EXA_API_KEY"

package/.codex/mcp/memory-bridge.toml.example

@@ -0,0 +1,15 @@
+[mcp_servers.memory-bridge]
+# Example only: replace with your own MCP memory bridge.
+# Keep this at the user level unless the server is repo-safe and secret-free.
+
+# HTTP remote example:
+# url = "https://memory.example.com/mcp"
+# bearer_token_env_var = "MEMORY_BRIDGE_API_KEY"
+
+# Stdio local-process example:
+# command = "npx"
+# args = ["-y", "@your-org/memory-bridge-mcp"]
+
+# Codexkit rule:
+# repo-visible docs remain canonical truth.
+# Sync durable conclusions back into `.codex/context/` or `.codex/memory/`.

package/.codex/mcp/memory.toml.example

@@ -0,0 +1,6 @@
+[mcp_servers.memory]
+command = "bash"
+args = ["-lc", ".codex/scripts/memory_search.sh \"$MEMORY_QUERY\""]
+
+[mcp_servers.memory.env]
+MEMORY_QUERY = "replace-me"

package/.codex/mcp/ref.toml.example

@@ -0,0 +1,13 @@
+# Ref — Documentation search and reading
+# Provides: ref_search_documentation, ref_read_url
+# Requires: REF_API_KEY (get from https://ref.tools → Dashboard)
+#
+# Keep the key in your shell or .codex/.env, then launch Codex with:
+#   codexkit run
+#
+# Add this to ~/.codex/config.toml (NOT project-level config):
+
+[mcp_servers.ref]
+command = "npx"
+args = ["-y", "ref-tools-mcp@latest"]
+env_vars = ["REF_API_KEY"]

package/.codex/mcp/tilth.toml.example

@@ -0,0 +1,10 @@
+# Tilth — AST-aware code search, smart file reading, hash-anchored edits
+# Provides: tilth_search, tilth_read, tilth_files, tilth_edit, tilth_deps
+# No API key needed
+# NOTE: Already enabled in .codex/config.toml by default
+
+[mcp_servers.tilth]
+command = "npx"
+args = ["-y", "tilth", "--mcp", "--edit"]
+startup_timeout_sec = 30.0
+tool_timeout_sec = 60.0

package/.codex/memory/README.md

@@ -0,0 +1,29 @@
+# Memory
+
+Codexkit stores durable project memory in markdown files under this directory.
+This directory is part of the repo-visible memory model, not a hidden semantic memory engine.
+
+## Canonical Boundaries
+
+- `project/` holds durable project facts, state, goals, roadmap, and gotchas.
+- `research/` holds deeper investigations that should stay inspectable in git.
+- `_templates/` holds starter templates for repeatable memory updates.
+
+The canonical stop point for pause/resume is `.codex/context/session-context.md`.
+If `memory/session-context.md` exists, treat it as a legacy compatibility file, not the primary home for new session checkpoints.
+
+## One Home Per Concept
+
+- session stop point -> `.codex/context/session-context.md`
+- session milestone trail -> `.codex/context/worklog.md`
+- durable current state and blockers -> `project/state.md`
+- true architecture or workflow decisions -> `.codex/context/decision-log.md`
+- durable project facts and constraints -> `project/*.md`
+- deep investigation notes -> `research/*.md`
+
+## What Not To Store Here
+
+- raw command output dumps
+- speculative ideas that are not yet decisions
+- duplicate copies of worklog or session-context entries
+- the only copy of a decision that teammates need to review

package/.codex/memory/_templates/README.md

@@ -0,0 +1,26 @@
+# Memory Templates
+
+Use these templates to keep durable memory updates consistent and non-overlapping.
+
+## Canonical Templates
+
+- `gotcha.md` -> reusable constraint, footgun, or operational warning
+- `research.md` -> deeper investigation with evidence and recommendation
+- `session-context.md` -> compact pause/resume stop point
+- `handoff.md` -> structured session handoff summary
+- `state.md` -> durable current state, blockers, and next actions
+- `tech-stack.md` -> stable tooling facts and verification commands
+- `project.md` -> durable project goals and success criteria
+- `user.md` -> durable user preferences and workflow notes
+- `roadmap.md` -> phase-based delivery direction
+
+## Legacy / General Templates
+
+These remain available, but they are not the primary memory routing model:
+
+- `proposal.md`
+- `design.md`
+- `prd.md`
+- `tasks.md`
+
+Prefer the canonical templates above when recording durable project memory.

package/.codex/memory/_templates/design.md

@@ -0,0 +1,15 @@
+# Design
+
+Use when a design write-up is worth keeping as durable research context.
+
+## Problem
+
+## Goals
+
+## Constraints
+
+## Proposed Approach
+
+## Risks
+
+## Verification

package/.codex/memory/_templates/gotcha.md

@@ -0,0 +1,9 @@
+# Gotcha
+
+## Constraint
+
+## Why It Matters
+
+## What To Do Instead
+
+## Scope

package/.codex/memory/_templates/handoff.md

@@ -0,0 +1,9 @@
+# Handoff
+
+## Done
+
+## In Progress
+
+## Blockers
+
+## Next Actions

package/.codex/memory/_templates/prd.md

@@ -0,0 +1,13 @@
+# PRD
+
+Use when a product requirement summary is intentionally stored as durable reference.
+
+## Summary
+
+## User Outcomes
+
+## Requirements
+
+## Acceptance Criteria
+
+## Risks

package/.codex/memory/_templates/project.md

@@ -0,0 +1,9 @@
+# Project Memory
+
+## Vision
+
+## Goals
+
+## Success Criteria
+
+## Context Notes

package/.codex/memory/_templates/proposal.md

@@ -0,0 +1,13 @@
+# Proposal
+
+Use when storing a durable change proposal that still needs review.
+
+## Change
+
+## Motivation
+
+## Scope
+
+## Tradeoffs
+
+## Decision

package/.codex/memory/_templates/research.md

@@ -0,0 +1,9 @@
+# Research Note
+
+## Question
+
+## Findings
+
+## Evidence
+
+## Recommendation

package/.codex/memory/_templates/roadmap.md

@@ -0,0 +1,11 @@
+# Roadmap
+
+Use for durable phase-based direction, not transient session planning.
+
+## Current Phase
+
+## Near-Term Milestones
+
+## Backlog
+
+## Risks

package/.codex/memory/_templates/session-context.md

@@ -0,0 +1,7 @@
+# Session Context
+
+## Current Focus
+
+## Open Questions
+
+## Next Actions

package/.codex/memory/_templates/state.md

@@ -0,0 +1,11 @@
+# State
+
+## Status
+
+## Recent Completed Work
+
+## Active Decisions
+
+## Blockers
+
+## Next Actions

package/.codex/memory/_templates/tasks.md

@@ -0,0 +1,9 @@
+# Tasks
+
+Use only for task snapshots that need to be preserved as durable context.
+
+## Active
+
+## Blocked
+
+## Done

package/.codex/memory/_templates/tech-stack.md

@@ -0,0 +1,9 @@
+# Tech Stack
+
+## Languages
+
+## Runtime
+
+## Tooling
+
+## Verification Commands

package/.codex/memory/_templates/user.md

@@ -0,0 +1,7 @@
+# User Memory
+
+## Preferences
+
+## Workflow
+
+## Communication Notes

package/.codex/memory/project/gotchas.md

@@ -0,0 +1,5 @@
+# Gotchas
+
+- Keep skill source of truth in `.codex/skills/`; if install creates `.agents/skills`, treat it as disposable local wiring only.
+- Validate install scripts after changing prompts, hooks, or agent definitions.
+- Do not claim memory automation works unless the underlying files and scripts exist.

package/.codex/memory/project/project.md

@@ -0,0 +1,12 @@
+# Project Memory
+
+## Vision
+
+Codexkit is a repo-distributed operating kit for OpenAI Codex CLI: prompts, agents,
+hooks, docs, and memory conventions that help sessions start fast and finish cleanly.
+
+## Goals
+
+- Keep setup simple and git-friendly.
+- Make workflows reproducible across projects.
+- Preserve useful context without adding a database.

package/.codex/memory/project/roadmap.md

@@ -0,0 +1,15 @@
+# Roadmap
+
+## Current Phase
+
+- Phase 4: Scale and production-readiness hardening.
+
+## Near-Term Milestones
+
+- Close audit and validation gaps.
+- Keep install, docs, and hooks aligned with real repo state.
+
+## Backlog
+
+- Additional specialty skills and MCP examples.
+- More robust release automation.

package/.codex/memory/project/state.md

@@ -0,0 +1,22 @@
+# State
+
+## Status
+
+- Current release focus: keep installers, validation, and shipped inventory aligned.
+- Blockers: none recorded.
+
+## Recent Completed Work
+
+- Baseline context system established in `.codex/context/`.
+
+## Active Decisions
+
+- Skills are stored canonically in `.codex/skills/`.
+
+## Blockers
+
+- None recorded.
+
+## Next Actions
+
+- Keep install, hooks, docs, and packaged assets aligned.

package/.codex/memory/project/tech-stack.md

@@ -0,0 +1,19 @@
+# Tech Stack
+
+## Languages
+
+- Markdown
+- TOML
+- Bash
+
+## Runtime
+
+- OpenAI Codex CLI
+
+## Verification Commands
+
+- `bash tests/smoke/test_structure.sh`
+- `bash tests/smoke/test_scripts.sh`
+- `bash tests/integration/test_hooks.sh`
+- `bash tests/integration/test_install.sh`
+- `bash install/validate.sh`

package/.codex/memory/project/user.md

@@ -0,0 +1,10 @@
+# User Memory
+
+## Preferences
+
+- Record maintainer or team collaboration preferences here when needed.
+
+## Workflow
+
+- Implement from repo evidence first.
+- Preserve user edits and keep changes scoped.

package/.codex/memory/research/.gitkeep

@@ -0,0 +1 @@
+

package/.codex/memory/session-context.md

@@ -0,0 +1,18 @@
+# Session Context
+
+Legacy compatibility file only.
+
+Use `.codex/context/session-context.md` as the canonical stop point for pause/resume.
+Do not start writing new session checkpoints here unless a migration or compatibility workflow explicitly requires it.
+
+## Current Focus
+
+- None recorded.
+
+## Open Questions
+
+- None recorded.
+
+## Next Actions
+
+- None recorded.

package/.codex/plans/README.md

@@ -0,0 +1,7 @@
+# Plans
+
+Store implementation plans here when work needs a durable, repo-local handoff.
+
+- Use one markdown file per plan.
+- Keep discovery, waves, risks, and verification sections explicit.
+- Prefer linking to prompts, PRDs, and research notes instead of duplicating them.