CodeOSX - Claude CLI for every Mac on OS X

 ______ __ ____ ______ __
/ ____/___ ____/ /__ / __ \/ ___/ |/ /
/ / / __ \/ __ / _ \/ / / /\__ \| / / /___/ /_/ / /_/ / __/ /_/ /___/ / | \____/\____/\__,_/\___/\____//____/_/|_| 

Overview

CodeOSX is a complete Claude CLI implementation written in GNU C89, designed to run on Mac OS X 10.0 (Cheetah, 2001) through modern macOS.

Features

• GNU C89 Implementation - Compiles with GCC 2.95+ for maximum compatibility
• ReAct Agent System - Autonomous reasoning and tool execution loop
• 10 Built-in Tools - File ops, shell commands, search, todos, interactive user questions
• Rich Terminal UI - Interactive question prompts with arrow navigation and checkboxes
• Session Persistence - SQLite-based conversation history
• TLS 1.2 Support - Powered by BearSSL for secure API communication
• Debug Mode - Optional detailed logging to stderr for troubleshooting
• Zero Dependencies - Single self-contained binary (1.2MB)
• Cross-Platform - PowerPC, Intel i386, x86_64, ARM64 (Apple Silicon)

Quick Start

Building CodeOSX

# Prerequisites# - GCC or Clang# - Make# - Download BearSSL 0.6 and SQLite 3.46.1 (see below)# 1. Download dependenciescd src
wget https://bearssl.org/bearssl-0.6.tar.gz
tar xzf bearssl-0.6.tar.gz
mv bearssl-0.6 bearssl
wget https://www.sqlite.org/2024/sqlite-amalgamation-3460100.zip
unzip sqlite-amalgamation-3460100.zip
mkdir -p sqlite
mv sqlite-amalgamation-3460100/sqlite3.* sqlite/
cd ..
# 2. Build
make clean && make
# 3. Runexport ANTHROPIC_API_KEY="sk-ant-your-key-here"
./build/codeosx

Running

# Set your API keyexport ANTHROPIC_API_KEY="sk-ant-..."# Run CodeOSX
./build/codeosx
# Show version
./build/codeosx --version
# Show help
./build/codeosx --help
# Run with debug output
./build/codeosx --debug 2> debug.txt

Command-Line Options

Option	Description
--version	Show version information
--help	Show help message
--debug	Enable debug output to stderr

Interactive Commands

Command	Description
/help	Show available commands
/quit	Exit the program
/exit	Exit the program
Any text	Send message to Claude agent

Available Tools

The agent has access to 10 tools:

File Operations

• read_file - Read contents of a file
• write_file - Write contents to a file
• edit_file - Edit file by replacing text
• list_directory - List files in a directory

Shell Execution

• bash - Execute bash commands with timeout

Search

• grep - Search for patterns in files (regex)
• find_files - Find files matching a pattern (glob)

Task Management

• todos_read - Read todo list from ~/.codeosx/todos.json
• todos_write - Write todo list

User Interaction

• ask_user - Interactive question prompts with:
  • Single-select and multi-select questions
  • Arrow key navigation (↑↓) and checkbox toggling
  • Custom text input option
  • Confirmation page before submission
  • Clean inline UI that doesn't take over the screen

Configuration

Environment variables:

Variable	Description	Default
ANTHROPIC_API_KEY	Your API key	Required
CODEOSX_API_HOST	API hostname	api.anthropic.com
CODEOSX_API_PORT	API port	443
CODEOSX_USE_HTTPS	Use HTTPS	1 (true)
CODEOSX_MODEL	Claude model	claude-sonnet-4-5-20250929
CODEOSX_MAX_TOKENS	Max response tokens	4096
CODEOSX_MAX_ITERATIONS	Agent max iterations	25
CODEOSX_SESSION_DB_PATH	Session database path	~/.codeosx/sessions.db

Architecture

┌─────────────────────────────────────────────────────────────┐
│ CodeOSX CLI │
├─────────────────────────────────────────────────────────────┤
│ │
│ main.c ──→ CLI (REPL) ──→ Agent (ReAct Loop) │
│ │ │
│ ├──→ Tool Registry │
│ │ ├─ File Tools │
│ │ ├─ Shell Tool │
│ │ ├─ Search Tools │
│ │ ├─ Todo Tools │
│ │ └─ Ask User Tool │
│ │ │
│ ├──→ HTTP Client (BearSSL TLS)│
│ │ │
│ └──→ Session Manager (SQLite) │
│ │
└─────────────────────────────────────────────────────────────┘

Project Structure

codeosx/
├── src/
│ ├── main.c # Entry point
│ ├── cli.c/h # REPL interface
│ ├── agent.c/h # ReAct agent loop
│ ├── config.c/h # Configuration
│ ├── http_client.c/h # TLS HTTP client (BearSSL)
│ ├── session.c/h # Session persistence (SQLite)
│ ├── terminal.c/h # Terminal control (raw mode, arrow keys)
│ ├── util.c/h # Utilities
│ ├── cJSON.c/h # JSON parser (bundled)
│ ├── bearssl/ # BearSSL 0.6 (TLS library)
│ ├── sqlite/ # SQLite 3.46.1 (database)
│ └── tools/
│ ├── registry.c/h # Tool registry
│ ├── schemas.h # Tool JSON schemas
│ ├── filesystem.c/h # File operations
│ ├── shell.c/h # Bash execution
│ ├── search.c/h # Grep and find
│ ├── todos.c/h # Todo management
│ ├── ask_user.c/h # User interaction (tool handler)
│ └── ask_user_ui.c/h # Rich terminal UI (questions, navigation)
├── build/ # Build output
├── tests/ # Test programs
├── Documentation/ # Design docs
└── Makefile # Build system

Technical Details

• Language: C89/ANSI C (GNU C89 for BearSSL inline keyword support)
• Compiler: GCC 2.95+ or Clang
• TLS Library: BearSSL 0.6 (504KB)
• Database: SQLite 3.46.1 amalgamation (1.4MB)
• JSON Parser: cJSON (79KB, bundled)
• Binary Size: ~1.2MB (statically linked)
• Lines of Code: ~2,600 (excluding dependencies)

Platform Support

Tested

• macOS 14+ (Apple Silicon ARM64)
• macOS 14+ (Intel x86_64)

Planned Testing

• Mac OS X 10.7 Lion (Intel x86_64, GCC 4.2)
• Mac OS X 10.4 Tiger (PowerPC G4/G5, GCC 4.0)
• Mac OS X 10.3 Panther (PowerPC G3/G4, GCC 3.3)
• Mac OS X 10.0 Cheetah (PowerPC G3, GCC 2.95)

Implementation Progress

• ✅ Phase 0: Foundation & Dependencies (100%)
• ✅ Phase 1: Core Infrastructure (100%)
• ✅ Phase 2: Tool System (100%)
• ✅ Phase 3: Agent System (100%)
• ✅ Phase 4: Session Management (100%)
• 🚧 Phase 5: Polish & Testing (In Progress)

See PROGRESS.md for detailed status.

Development

# Clean build
make clean && make
# Run tests
make test# Remove all generated files
make distclean

Debugging

When troubleshooting issues, use the --debug flag to capture detailed output:

# Capture debug output to file
./build/codeosx --debug 2> debug.txt
# Debug output includes:# - Tool execution ([Tool] Using...)# - Tool results ([Result]...)# - UI rendering details (when using ask_user)# - Cursor positioning and line counts

Debug messages go to stderr while the UI appears on stdout, ensuring they don't interfere with the user interface.

Documentation

• ARCHITECTURE.md - System design
• IMPLEMENTATION_PLAN.md - Development roadmap
• DECISIONS.md - Design decisions
• PROGRESS.md - Implementation progress
• CONTRIBUTING.md - Development workflow guide
• CHANGELOG.md - Version history

Requirements

Build Time

• C compiler (GCC 2.95+ or Clang)
• Make
• BearSSL 0.6 source
• SQLite 3.46.1 amalgamation source

Runtime

• Mac OS X 10.0+ (or modern macOS)
• Anthropic API key
• Internet connection

Known Limitations

• Empty trust anchors array (TLS certificate verification not fully implemented)
• Session persistence saves user messages only (agent responses TBD)
• Binary size is 1.2MB due to static SQLite linking (trade-off for portability)

License

MIT License

Credits

• Built with BearSSL by Thomas Pornin
• Database powered by SQLite
• JSON parsing by cJSON
• Powered by Anthropic Claude

---

Status: Alpha

Last Updated: 2026-01-16