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 dependencies
cd 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. Run
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
./build/codeosx

Running

# Set your API key
export 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

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
Documentation		Documentation
scripts		scripts
src.old		src.old
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLEANUP_BACKUP_LIST.txt		CLEANUP_BACKUP_LIST.txt
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
Makefile.old		Makefile.old
README.md		README.md
cli_ui_reference.txt		cli_ui_reference.txt
hello_world.md		hello_world.md

Folders and files

Latest commit

History

Repository files navigation

CodeOSX - Claude CLI for every Mac on OS X

Overview

Features

Quick Start

Building CodeOSX

Running

Command-Line Options

Interactive Commands

Available Tools

File Operations

Shell Execution

Search

Task Management

User Interaction

Configuration

Architecture

Project Structure

Technical Details

Platform Support

Tested

Planned Testing

Implementation Progress

Development

Debugging

Documentation

Requirements

Build Time

Runtime

Known Limitations

License

Credits

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages