Skip to content

QUICKSTART.md

Latest commit

 

History

History
238 lines (153 loc) · 6.87 KB

QUICKSTART.md

File metadata and controls

238 lines (153 loc) · 6.87 KB

open-agent-kit Quick Start Guide

Get started with open-agent-kit in under 5 minutes.

Installation

Homebrew (macOS — Recommended)

Homebrew handles Python version pinning automatically — no need to specify --python.

brew install goondocks-co/oak/oak-ci

Install Script (macOS / Linux)

The install script detects your environment and handles everything automatically.

curl -fsSL https://raw.githubusercontent.com/goondocks-co/open-agent-kit/main/install.sh | sh

Windows PowerShell

irm https://raw.githubusercontent.com/goondocks-co/open-agent-kit/main/install.ps1 | iex

Alternative: Using pipx

Requires Python 3.12 or 3.13. If your default python3 is a different version (e.g. 3.14 via Homebrew), specify the interpreter explicitly with --python.

pipx install oak-ci --python python3.13

Alternative: Using uv

Requires Python 3.12 or 3.13. If your default Python is a different version, specify it with --python.

uv tool install oak-ci --python python3.13

Alternative: Using pip

Requires Python 3.12 or 3.13.

pip install oak-ci

Verify installation:

oak --version

Step 1: Initialize Your Project

Navigate to your project directory and run:

oak init

This will:

  1. Prompt you to select one or more AI agents (Claude, Copilot, Codex, Cursor, Gemini, Windsurf)
  2. Prompt you to select which languages to support (Python, JavaScript, TypeScript)
  3. Installs agent skills and mcp tools for your selected agents

Step 2: Create Your Constitution

A constitution formalizes your project's engineering standards, architecture patterns, and team conventions. This is the foundation for all other oak workflows.

Why Create a Constitution First?

  • Guides all AI agents - Every agent references the constitution for context
  • Codifies team conventions - Makes implicit standards explicit

Creating Your Constitution

Use your AI agent's command:

use the project governance skill to create my project's constitution

The AI will:

  1. Check for existing agent instructions and use them as context
  2. Analyze your codebase for patterns (testing, linting, CI/CD, etc.)
  3. Create oak/constitution.md with comprehensive standards
  4. Update agent instruction files with constitution references (additively)

For Teams With Existing Agent Instructions

If your team already has agent instruction files (like .github/copilot-instructions.md), open-agent-kit will:

  • Preserve your existing content - Never overwrites
  • Use it as context - Incorporates your conventions into the constitution
  • Append references - Links existing files to the new constitution
  • Create backups - Saves .backup files before any changes

After Creating Your Constitution

# View the constitution
cat oak/constitution.md

Step 3: Start Codebase Intelligence (Optional)

The CI daemon provides semantic code search, session history, and project memories for your AI agents.

# Start the daemon with browser UI
oak team start --open

This gives your agents access to:

  • Semantic search across code and memories
  • Session history to recall past decisions
  • MCP server for direct tool access

Step 4: Enable Team Sync (Optional)

Team Sync lets multiple machines share codebase memories and search results via a Cloudflare Worker relay, enabling cross-team semantic intelligence without exposing your local database.

For full setup, see the Team Sync guide in the documentation.

Troubleshooting

Python 3.14+ errors

OAK requires Python 3.12 or 3.13. If your default python3 points to 3.14 (common with Homebrew), the simplest fix is to use the Homebrew formula (which pins Python 3.13 automatically):

brew install goondocks-co/oak/oak-ci

Or reinstall with an explicit interpreter:

pipx install oak-ci --python python3.13 --force

oak command not found

# Check if installed
which oak

# Reinstall via Homebrew (macOS)
brew reinstall oak-ci

# Or reinstall via the install script (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/goondocks-co/open-agent-kit/main/install.sh | sh

# Or reinstall via pipx
pipx install oak-ci --python python3.13

.oak directory not found

Run oak init first to initialize the project.

AI agent commands not showing up

# Add an agent to existing installation
oak init --agent claude

Agent commands are installed in their native directories (.claude/commands/, .github/agents/, etc.).

CI Daemon Issues

⚠️ Gotcha: When the coding agent rebuilds the UI (e.g., during hot-reload), it restarts the MCP server process. The new process may use a stale auth token, causing authentication failures until you reconnect.

MCP server authentication errors after restart:

# Stop and restart the daemon
oak team stop && oak team start

⚠️ Gotcha: The daemon returns 401 Missing Authorization header when the .oak/ci/.daemon_token file is absent or the OAK_CI_TOKEN environment variable was never set. The client reads the token file unconditionally and crashes if it doesn't exist.

Daemon returns 401 on every request:

# Stop the daemon, then restart — it will regenerate the token file
oak team stop && oak team start

If the problem persists, verify the token file exists:

ls -la .oak/ci/.daemon_token

⚠️ Gotcha: The port file contents must be purely numeric. If the file contains whitespace or non-numeric characters, the daemon may fail to start with a ValueError.

Daemon fails to start with port error:

# Clear stale port files
rm -f ~/.oak/daemon.port .oak/daemon.port
oak team start

⚠️ Gotcha: If the repository is nested inside another git repo, the installer may identify the wrong project root, leading to mis-located hook files.

Wrong project root detected:

Ensure you run oak init from the actual project root (the directory containing your .git folder).

Upgrading

# Homebrew
brew upgrade oak-ci

# pipx / uv
pipx upgrade oak-ci   # or: uv tool upgrade oak-ci

Then upgrade project templates: oak upgrade --dry-run to preview, oak upgrade to apply.

⚠️ Gotcha: Do not run oak upgrade concurrently in multiple terminals. The upgrade process writes to a shared temp file without an atomic lock — a second concurrent run can overwrite the first's download, resulting in a corrupted binary and a crash on next start. If this happens, reinstall via your original install method (Homebrew, pipx, or the install script).

Next Steps