How to Deploy the AI-Berkshire System: Complete Installation Guide for Claude Code and Codex

Deploy the ai-berkshire system by installing the Claude Code or Codex CLI, cloning the xbtlin/ai-berkshire repository, and running the provided installation scripts to register the 19 built-in investment research skills.

The ai-berkshire system is a modular, three-layer architecture (Skill → Agent → Tool) designed for production-grade financial analysis. You can deploy the ai-berkshire system locally on any machine supporting Python 3.10+, using either Anthropic's Claude Code or OpenAI's Codex as the AI client interface.

Prerequisites and System Requirements

Before deploying the ai-berkshire system, ensure your environment meets these specifications:

• Python 3.10 or higher (required by the tool layer for precise financial calculations)
• Node.js and npm (for Claude Code installation) or curl/Homebrew (for Codex)
• Network access to fetch the repository and client binaries
• Optional: A ~/.env file configured for external data sources (see .env.example in the repository)

Client Installation Options

The ai-berkshire system supports two AI clients. Choose one based on your preferred ecosystem.

Option 1: Claude Code (Anthropic)

Claude Code provides the /skill command interface that launches AI agents. Install it globally via npm:

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

Verify the installation:

claude --version

Option 2: Codex (OpenAI)

Codex offers an alternative CLI with slash-prompt compatibility. Install it using the official installer or via npm/Homebrew:

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

Verify the installation:

codex --version

Repository Setup and Skill Installation

Once your client is installed, deploy the ai-berkshire system by setting up the repository and installing the skill packages.

1. Clone the repository:

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

2. Install the skills for your chosen client:

• For Claude Code: Run ./scripts/install-claude-commands.sh to copy skill files into the client's global commands folder.
• For Codex: Run ./scripts/install-codex-skills.sh to generate canonical skill bundles from skills/*.md. Optionally run ./scripts/install-codex-prompts.sh for slash-prompt compatibility.

These scripts map the canonical skills/*.md definitions to client-specific formats, registering all 19 built-in skills (such as /investment-research and /news-pulse) with your CLI.

Understanding the Three-Layer Architecture

The ai-berkshire system implements a Skill → Agent → Tool hierarchy as defined in the source code:

• Skill Layer: Natural-language command parsers located in skills/*.md that map user requests to concrete Python scripts or LLM prompts.
• Agent Layer: Orchestration components (e.g., /investment-team) that spawn multiple parallel agents for deep research tasks.
• Tool Layer: Deterministic utilities like tools/financial_rigor.py that guarantee numeric accuracy for market-cap verification and valuation calculations.

When you invoke a skill, the client triggers this hierarchy: the Skill layer parses the request, the Agent layer coordinates parallel processing, and the Tool layer executes precise financial calculations.

Running Your First Skill

Verify your deployment by running a test command. The syntax differs slightly between clients.

Using Claude Code:

claude /investment-research 腾讯

Using Codex:

codex investment-research 腾讯

You can also call tools directly for pipeline integration without the AI client:

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

Maintaining and Syncing Updates

After modifying any skills/*.md file, synchronize the generated Codex artifacts to keep your deployment current:

python3 scripts/sync-codex-skills.py

If you use the slash-prompt layer, also run:

python3 scripts/sync-codex-prompts.py

Summary

• Deploy the ai-berkshire system by installing Claude Code or Codex, cloning the repository, and running scripts/install-claude-commands.sh or scripts/install-codex-skills.sh.
• The system requires Python 3.10+ and operates via a three-layer architecture: Skill (skills/*.md), Agent (parallel research teams), and Tool (tools/financial_rigor.py).
• Invoke skills using claude /skill-name or codex skill-name syntax.
• Use scripts/sync-codex-skills.py to update generated artifacts after editing source files.

Frequently Asked Questions

Do I need both Claude Code and Codex to deploy the ai-berkshire system?

No. The ai-berkshire system supports either client independently. Choose Claude Code if you prefer Anthropic's ecosystem, or Codex if you use OpenAI's models. The skills/*.md source files compile to both formats via the respective installation scripts in the scripts/ directory.

What Python version is required for the tool layer?

Python 3.10 or higher is required. The tool layer includes tools/financial_rigor.py and other deterministic utilities that rely on Python 3.10+ features for precise financial calculations and market data verification.

How do I update skills after modifying the source files?

After editing any skills/*.md file, run python3 scripts/sync-codex-skills.py to regenerate the Codex skill bundles. For Claude Code users, simply re-run ./scripts/install-claude-commands.sh to copy updated files to the client's global directory.

Can I run the ai-berkshire system in a CI/CD pipeline?

Yes. Since the system runs locally via CLI commands, you can embed claude /skill-name or codex skill-name calls in automation scripts. For pipeline use, invoke tools directly via Python (e.g., python3 tools/financial_rigor.py) to avoid interactive CLI requirements.

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