Build and Run CometixCode, a Rust Terminal AI Coding Assistant

What Is CometixCode?

CometixCode is a terminal-based AI coding assistant written in Rust. It is an independent, file-by-file reimplementation of Anthropic’s Claude Code terminal interface rather than an official Anthropic product.

CometixCode is unofficial, is not affiliated with Anthropic, and is not endorsed or supported by Anthropic. Claude and Claude Code are trademarks of Anthropic, PBC.

The original Claude Code terminal UI uses TypeScript with React and Ink. CometixCode recreates that structure in Rust using CometixTUI, a fork of the iocraft retained-mode terminal UI framework. TypeScript components map to Rust components, hooks map to hooks, and intentional architectural differences are documented in the source.

The project is still a work in progress. Large portions of the interactive loop, tool execution, permissions, Model Context Protocol integration, and slash commands are implemented, but some areas remain partial.

Key Features and Architecture

• Rust-based terminal UI: The interface is implemented with a React-style component and hook model.
• Close architectural port: The project follows Claude Code’s published CLI structure file by file instead of replacing it with a new design.
• Interactive coding workflow: Major parts of the assistant loop and tool execution system are implemented.
• Permissions and commands: Permission handling and slash-command support are substantially implemented.
• MCP support: Model Context Protocol functionality is included, although the overall project remains under development.
• Enhanced terminal primitives: CometixTUI supplies row-level diffing, event propagation, SIGCONT recovery, IME cursor support, bracketed paste, and grid layout.
• External file search: CometixCode uses a separate ripgrep executable instead of compiling ripgrep into its own binary.

Prerequisites

Before building CometixCode, install the following dependencies:

• Rust 1.87 or newer, using Rust edition 2024.
• ICU4C, which is required by the rust_icu_* crates through pkg-config.

Install ICU4C on macOS

Homebrew installs ICU4C as a keg-only package. Install it and add its pkgconfig directory to the lookup path:

brew install icu4c
export PKG_CONFIG_PATH="$(brew --prefix icu4c)/lib/pkgconfig"

Run the export in the shell where you build CometixCode. If you work on the project regularly, add the variable to the appropriate shell configuration file.

Install ICU4C on Debian or Ubuntu

sudo apt install libicu-dev pkg-config

Build CometixCode

Open a terminal in the repository root and create an optimized release build:

cargo build --release

The resulting binary is named cometix. A release build is appropriate for normal use because it enables Rust’s release optimizations.

Run the Assistant

Build and launch CometixCode through Cargo with:

cargo run --release

This starts the terminal interface using the release profile. Because the project is under active development, expect some workflows to be incomplete even though major interactive, tool, permission, MCP, and command functionality is already present.

Basic Diagnostic Command

Inside CometixCode, use the following slash command to inspect the configured environment, including which ripgrep executable is being used:

/doctor

This is especially useful when file search is unavailable or when you need to confirm whether CometixCode selected a packaged or host-installed rg binary.

Configure ripgrep for File Search

CometixCode delegates file searches to rg, the ripgrep command-line tool. The ripgrep executable remains an external asset and is never compiled into the cometix executable.

CometixCode searches for ripgrep in this order:

1. vendor/ripgrep/<arch>-<os>/rg next to the executable, as used by release archives.
2. vendor/ripgrep/<arch>-<os>/rg in the source tree, as used during development.
3. The host system’s rg command available through PATH.

You can therefore place a pinned ripgrep build in the matching vendor/ripgrep/ platform directory or install ripgrep on the host and make sure rg is on PATH.

Force the Host ripgrep Binary

Set USE_BUILTIN_RIPGREP to 0 when you want CometixCode to skip vendored ripgrep assets and use the host executable:

USE_BUILTIN_RIPGREP=0 cargo run --release

After launching, run /doctor to verify the selected binary.

Run the Test Suite Correctly

CometixCode has process-wide state, including environment variables and OnceLock caches. Running every test as threads in one process can allow state to leak between tests, so plain cargo test is not considered a valid quality gate for this crate.

The project instead uses cargo-nextest, invoked through just. This gives each test its own process and pins host state that a test might otherwise inherit.

Run the Full Suite

just test

This is the project’s required full test gate.

Run Tests Matching a Pattern

just t <pattern>

Replace <pattern> with a substring used to filter the tests you want to execute.

Perform a Fast Code Check

just check

This performs type and borrow checking without linking, making it useful for quick feedback while editing Rust code.

Advanced Development Tips

• Prefer release mode for normal use: Use cargo run --release to run the optimized build specified by the project documentation.
• Check ICU discovery first: On macOS, a build failure involving ICU may indicate that PKG_CONFIG_PATH does not include Homebrew’s ICU4C metadata directory.
• Diagnose file search with /doctor: Confirm the exact ripgrep executable selected before changing vendored files or system configuration.
• Pin ripgrep when reproducibility matters: Place the intended binary under the platform-specific vendor/ripgrep/ path rather than relying on whichever version happens to be installed globally.
• Do not substitute cargo test for the project gate: Use just test so tests receive the process isolation expected by the codebase.
• Consult the justfile for test rationale: Its header documents the measurements behind the selected testing strategy.

License Considerations

CometixCode is distributed under the AGPL-3.0-only license. The license includes a network-use clause: if you operate a modified version as a network service, its users are entitled to the corresponding modified source code.

Conclusion

CometixCode provides a Rust-based recreation of the Claude Code terminal architecture using CometixTUI. Once Rust, ICU4C, and an appropriate ripgrep executable are available, you can build and launch it with Cargo, inspect search configuration through /doctor, and validate changes with the project’s process-isolated just test workflow.