# Project Context

**Project**: Cody CLI — AINative Studio's AI-powered coding assistant
**Compatible With**: Claude Code, Gemini CLI, and other AI coding assistants

---

## Project Overview

Cody CLI is a fork/rebrand of Claude Code, building AINative Studio's terminal-based AI coding assistant. It connects to AINative's API gateway (Kong) which routes to multiple LLM providers. The CLI supports OAuth 2.1 + PKCE authentication, MCP (Model Context Protocol) servers, streaming chat completions, tool use, sub-agents, and a rich terminal UI built with Ink/React.

**Current Version**: 0.7.1
**Status**: Active Development — SDK works, chat completions API confirmed working

---

## Repository Paths

### Primary Repository
**Path**: `/Users/aideveloper/Desktop/cody-cli`
**GitHub**: `https://github.com/AINative-Studio/cody-cli`
**Framework**: Bun + TypeScript + React (Ink terminal UI)
**Status**: Active Development

---

## Tech Stack

- **Runtime**: Bun >= 1.1.0 (also supports Node >= 18 via thin wrapper)
- **Language**: TypeScript (ES2022, JSX, bundler module resolution)
- **UI Framework**: Ink 5.0 + React 19.1.0 (terminal UI)
- **CLI Framework**: Commander.js 12.0
- **AI SDK**: @anthropic-ai/sdk 0.82.0 (Beta Messages API)
- **MCP**: @modelcontextprotocol/sdk 1.29.0
- **Observability**: OpenTelemetry (traces, metrics, logs)
- **Build**: Bun bundler (TypeScript -> JS bundle -> optional native binary)
- **Testing**: bun:test (built-in test runner)
- **Deployment**: npm registry (@ainative/cody-cli), Homebrew tap
- **Package Manager**: Bun (bun.lock)

---

## Architecture

### System Flow
```
Developer -> Cody CLI -> Kong API Gateway -> Backend LLMs
                |
                +-> MCP Servers (ZeroDB, Chrome, etc.)
                +-> OAuth 2.1 + PKCE (api.ainative.studio)
                +-> Local tools (Bash, FileRead, FileWrite, etc.)
```

### Two CLI Modes
1. **Thin Wrapper** (`bin/cody.js`): Node.js launcher, auto-installs Bun
2. **Full Binary** (`cody-bin`): ~80MB self-contained Bun-compiled binary

### Source Directory Structure
```
src/
  entrypoints/       # CLI bootstrap (cli.tsx, init.ts, mcp.ts, sdk/)
  commands/           # 100+ slash commands
  tools/              # LLM-callable tools (Bash, FileRead, FileWrite, Glob, Grep, Agent, MCP)
  services/           # Business logic (oauth, mcp, api, analytics, compact, memory)
  components/         # 140+ Ink/React UI components
  hooks/              # 85+ React hooks
  utils/              # 330+ utility modules
  bridge/             # Remote control / bridge mode
  skills/             # Loadable skill system
  tasks/              # Task tracking subsystem
  context/            # Context window management
  state/              # Application state management
  main.tsx            # Main application loop & Ink render tree
  commands.ts         # Command registry & dispatch
```

### Build Pipeline
```
TypeScript (src/) -> bun build -> dist/cli.js (JS bundle)
                                      |
                                      +-> bun build --compile -> cody-bin (native binary)
```

---

## Services & APIs

### Backend API
**Base URL**: `https://api.ainative.studio`
**Auth**: OAuth 2.1 + PKCE (Client ID: `ainative-cody-cli-001`)
**Scopes**: `user:profile`, `user:inference`, `user:sessions:claude_code`, `user:mcp_servers`, `user:file_upload`, `org:create_api_key`

### MCP Servers
- **ZeroDB**: Vector database and storage (`https://api.ainative.studio/v1/mcp/zerodb-mcp/messages`)

### Available Models
- `qwen-coder-32b` (default)
- `qwen-coder-7b`
- `nouscoder-14b`
- `gemma-9b`
- `deepseek-r1-distill-qwen-7b`

---

## Development Workflow

### Local Development
```bash
bun install             # Install dependencies
bun run build           # Build JS bundle (dist/cli.js)
bun run start           # Run built CLI
bash compile.sh         # Build native binary (optional)
bun test                # Run all tests
bun test --coverage     # Run tests with coverage report
```

### Pre-Commit Checklist
1. Build — must succeed (`bun run build`)
2. Tests — all tests pass with >= 80% coverage (`bun test --coverage`)
3. No secrets, API keys, or tokens in code
4. No AI tool attribution in commit messages

---

## Git Workflow

### Branch Strategy
- `main` — production branch
- Feature branches: `feature/[name]`
- Bug fixes: `fix/[name]`

### Commit Rules (ZERO TOLERANCE)
**NEVER include in commits, PRs, or GitHub activity:**
- AI tool attribution of any kind ("Claude", "Anthropic", "ChatGPT", "Copilot")
- "Generated with", "Co-Authored-By" referencing AI tools
- "AI-generated" or "AI-assisted"

See `.ainative/git-rules.md` for complete rules.

---

## AI Agent Configuration

### Claude Code
- Primary agent configuration: `CLAUDE.md` (project root)
- Settings: `.claude/settings.json`
- Skills: `.claude/skills/`
- Hooks: `.claude/hooks/`

### Gemini CLI / Other AI Tools
- Project context: `.ainative/AINATIVE.md` (this file)
- Settings: `.ainative/settings.json`
- Skills: `.ainative/skills/`

---

## MCP Servers (Model Context Protocol)

See `.mcp.json` for MCP configuration.
See `.claude/settings.local.json` for enabled MCP servers.

---

## Key Files Reference

### Configuration
- `package.json` — Dependencies, scripts, npm publishing config
- `tsconfig.json` — TypeScript config (ES2022, bundler, JSX)
- `bunfig.toml` — Bun test runner config (30s timeout)
- `.mcp.json` — MCP server URLs
- `globals.d.ts` — Build-time MACRO type declarations

### Build
- `build.sh` — TypeScript -> JS bundle
- `compile.sh` — JS -> native binary
- `postbuild.sh` — Add shebang + chmod
- `install.sh` — End-user installer (curl | sh)

### Documentation
- `docs/ARCHITECTURE.md` — System design
- `docs/DEVELOPMENT.md` — Setup & contribution guide
- `docs/TESTING.md` — Test strategy & running tests
- `docs/MODELS.md` — Available models & selection

---

## Environment Variables

### Required
```bash
ANTHROPIC_API_KEY=your-api-key
ANTHROPIC_BASE_URL=https://api.ainative.studio
```

### Optional
```bash
ANTHROPIC_MODEL=qwen-coder-32b          # Override default model
CODY_E2E_API_KEY=your-e2e-key           # For live API tests
CODY_VERSION=0.7.1                       # Build version override
CODY_INTERNAL=1                          # Internal build flag
ANTHROPIC_SMALL_FAST_MODEL=qwen-coder-7b # Small model override
```

---

## Testing

### Testing Philosophy
- **TDD/BDD preferred**: Write tests before implementation
- **BDD-style**: `describe/it` syntax with `bun:test`
- **Minimum 80% coverage** for new features
- **Tests MUST be executed** with proof of passing before any commit/PR

### Test Structure
```
tests/
  setup.ts                    # Shared helpers, constants, spawn utilities
  e2e/
    cli-basics.test.ts        # Version flags, help, CLI modes
    branding.test.ts          # ASCII logo, brand colors, product names
    oauth-flow.test.ts        # OAuth URLs, client IDs, scopes
    api-integration.test.ts   # Live API calls (requires CODY_E2E_API_KEY)
    installer.test.ts         # install.sh validation
    build-artifacts.test.ts   # dist/cli.js, cody-bin, package.json
    mcp-connection.test.ts    # MCP server connectivity
```

### Running Tests
```bash
bun test                                    # All tests
bun test tests/e2e/cli-basics.test.ts      # Specific file
bun test --filter "version"                 # Pattern matching
bun test --coverage                         # With coverage report
CODY_E2E_API_KEY=sk-xxx bun test           # With live API
```

---

## Open Issues (17 active)

### Core Architecture
- #65 — Build usage-tracked dual-provider model routing
- #64 — Claude models fail through Anthropic adapter (BUG)
- #66 — [EPIC] Full roadmap

### Chrome Extension (#45)
- #51-#54 — Build Cody in Chrome MV3 extension

### Mobile App (#47)
- #57-#63 — React Native + Expo scaffold, QR pairing, streaming, notifications

---

**Team**: AINative Studio
**Repository**: AINative-Studio/cody-cli
