How to Set Up a Development Environment for AI Berkshire: Complete Setup Guide

Clone the repository, install Claude Code or Codex via npm, run the platform-specific install scripts in scripts/, and sync skill definitions using sync-codex-skills.py to activate the multi-agent investment research framework.

AI Berkshire is a multi-agent investment-research framework built on three logical layers (Skill → Agent → Tool) that requires specific client tools and skill synchronization to function locally. Setting up a development environment involves installing either Claude Code or Codex, deploying the generated skill packages, and preparing a Python toolchain for the auxiliary financial tools. This guide covers the complete setup process for macOS, Linux, and Windows environments.

Clone the Repository

Start by cloning the official repository and entering the project directory:

git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire

The repository root contains the full source tree, including all skill definitions in skills/*.md and installation helpers in the scripts/ directory.

Install the AI Client

AI Berkshire supports two primary clients. Choose one based on your preferred AI assistant.

Claude Code Installation

Install Claude Code globally using npm:

npm install -g @anthropic-ai/claude-code

This package provides the CLI interface that will host the AI Berkshire skills as global slash commands.

Codex Installation

Install Codex using one of the following methods:

# macOS / Linux - Official install script

curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Via npm

npm install -g @openai/codex

# Via Homebrew (macOS only)

brew install --cask codex

Install the Skills

After installing the client, you must install the generated skills that define the investment research workflows.

Claude Code Global Commands

Run the platform-specific install script to copy the skill markdown files into Claude Code's global command directory:

# Linux / macOS

./scripts/install-claude-commands.sh

# Windows PowerShell / CMD

.\scripts\install-claude-commands.bat

Codex Skill Packages

For Codex, install the generated skill packages and optional slash-prompt wrappers:

# Linux / macOS

./scripts/install-codex-skills.sh

# Optional: install slash-prompt compatibility layer

./scripts/install-codex-prompts.sh

# Windows PowerShell / CMD

.\scripts\install-codex-skills.bat

# Optional prompt install

.\scripts\install-codex-prompts.bat

The Codex installer executes scripts/sync-codex-skills.py to transform each skills/*.md file into a Codex skill package.

Synchronize Skill Definitions

The skills/*.md files serve as the single source of truth for the framework's capabilities. Whenever you modify a skill definition, regenerate the client artifacts:

# Regenerate Codex skill packages

python3 scripts/sync-codex-skills.py

# Verify changes without writing files

python3 scripts/sync-codex-skills.py --check

# Update slash-prompt wrappers (if using prompts)

python3 scripts/sync-codex-prompts.py

These scripts keep the generated codex-skills/*/SKILL.md and codex-prompts/*.md files synchronized with the master definitions.

Configure the Python Toolchain

The framework includes auxiliary tools for financial calculations and data validation located in tools/. Create an isolated Python environment:

python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

While the tools currently rely only on Python's standard library (decimal, csv, json, argparse), activating the environment ensures clean dependency management when requirements.txt dependencies are added.

Test the installation by running tools/financial_rigor.py with sample market data:

python3 tools/financial_rigor.py verify-market-cap \
  --price 510 --shares 9.11e9 --reported 4.65e12 --currency HKD

This validates the precise decimal arithmetic required for financial analysis.

Verify Your Installation

Confirm the setup by invoking a skill through your installed client:

Claude Code:

/investment-checklist 腾讯, 阿里巴巴

Codex (with prompt wrappers):

/prompts:investment-research 腾讯

Both commands should return structured investment analysis without errors, confirming that the skill definitions are properly registered and the framework is operational.

Summary

• Clone the xbtlin/ai-berkshire repository to access the skill definitions and install scripts.
• Install either Claude Code (@anthropic-ai/claude-code) or Codex via npm, curl, or Homebrew.
• Execute the platform-specific install scripts in scripts/ to deploy skills for your chosen client.
• Sync skill definitions after any edits to skills/*.md using scripts/sync-codex-skills.py.
• Prepare a Python virtual environment to run auxiliary tools like tools/financial_rigor.py.
• Verify functionality by running investment analysis commands through the installed client.

Frequently Asked Questions

What Python version is required for the AI Berkshire tools?

The auxiliary tools in tools/ require Python 3.x and use only the standard library modules (decimal, csv, json, argparse). No external pip dependencies are currently required for the core financial validation scripts, though a virtual environment is recommended for future compatibility.

Can I use both Claude Code and Codex simultaneously?

Yes. The repository maintains separate install scripts for each client. Run ./scripts/install-claude-commands.sh for Claude Code and ./scripts/install-codex-skills.sh for Codex. Both clients can share the same skills/*.md source files, though you must run sync-codex-skills.py after editing skills to update the Codex packages while Claude Code reads the markdown files directly.

How do I add a new skill to the framework?

Create a new markdown file in the skills/ directory following the existing format. After saving your changes, run python3 scripts/sync-codex-skills.py to regenerate the Codex skill packages. For Claude Code, simply rerun ./scripts/install-claude-commands.sh to copy the updated markdown files into the global commands directory.

Where are the generated Codex skill files stored?

The scripts/sync-codex-skills.py script generates Codex skill packages in the codex-skills/ directory, with each skill receiving its own subdirectory containing a generated SKILL.md file. The optional sync-codex-prompts.py script creates slash-prompt wrappers in codex-prompts/. These directories are kept in sync with the canonical definitions in skills/*.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}