Skip to content

README.md

Latest commit

 

History

History
280 lines (185 loc) · 8.66 KB

README.md

File metadata and controls

280 lines (185 loc) · 8.66 KB
Raw
Catalyst Code logo

Catalyst Code

A provider-independent coding agent for your terminal and browser.

Latest Release License GitHub Stars Website

What is Catalyst Code?

Catalyst Code, or CatCode, is an open-source coding-agent harness that runs on your own machine. Use it from a terminal or browser with cloud APIs, local models, self-hosted gateways, and OpenAI- or Anthropic-compatible providers.

Many coding agents lock you into one provider, require a hosted account, or hide how tools and agents operate. CatCode gives you control over the models, workspace, tools, approval rules, plugins, memory, and subagents used for each task. CatCode itself is self-hosted, and model requests are sent only to the provider endpoint you configure.

Why CatCode?

  • Use different providers and models without changing your coding workflow.
  • Approve destructive actions before files or commands are changed.
  • Keep agents inside the selected workspace with path-confinement protections.
  • Delegate work to subagents for research, planning, implementation, and review.
  • Choose your interface with both terminal and browser applications.
  • Extend the harness with plugins, hooks, skills, custom tools, and provider integrations.
  • Recover and continue work with persistent sessions, checkpoints, memory, and context compaction.

Install

Prebuilt releases are available for Linux, macOS, and Windows. You do not need Rust, Go, or another compiler unless you are building CatCode from source.

Choose either the browser interface or the terminal interface.

Browser interface

The browser interface is the recommended installation for most users.

It installs:

  • The catcode terminal application
  • The CatCode core
  • The browser frontend
  • A background service for the frontend

The browser frontend is a single Rust binary. No Node or Bun runtime is required.

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/catalystctl/catcode/refs/heads/master/install-web.sh | bash

After installation, open:

http://localhost:49283

To keep the frontend available only from the local machine:

curl -fsSL https://raw.githubusercontent.com/catalystctl/catcode/refs/heads/master/install-web.sh \
  | bash -s -- --expose local

To use another port:

curl -fsSL https://raw.githubusercontent.com/catalystctl/catcode/refs/heads/master/install-web.sh \
  | bash -s -- --port 8080

Windows

Open PowerShell (Windows Terminal, the PowerShell app, or classic PowerShell) and run:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/catalystctl/catcode/refs/heads/master/install.ps1))) -WithWeb

After installation, open:

http://localhost:49283

To install the frontend for local access only:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/catalystctl/catcode/refs/heads/master/install.ps1))) -WithWeb -Expose local

Terminal interface

Use this installation when you only want the terminal application.

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/catalystctl/catcode/refs/heads/master/install.sh \
  | bash -s -- --install

Windows

Open PowerShell (Windows Terminal, the PowerShell app, or classic PowerShell) and run:

irm https://raw.githubusercontent.com/catalystctl/catcode/refs/heads/master/install.ps1 | iex

Select the terminal installation from the installer menu.

After installation, open a new terminal window (PowerShell, Command Prompt, or Windows Terminal) so the updated user PATH is loaded. catcode.exe works from CMD as well as PowerShell once PATH reloads — no extra shim is required.

The agent's bash tool on Windows uses PowerShell by default (pwsh if installed, otherwise Windows PowerShell). With Microsandbox enabled it runs Linux bash in the guest instead. Optional override: CATALYST_CODE_SHELL (e.g. Git Bash path, or cmd.exe). Chat, file editing, search, and other native tools work without any extra shell install.

Homebrew

macOS users can install the terminal application from the CatCode Homebrew tap:

brew tap catalystctl/catcode
brew install catcode

Upgrade it later with:

brew upgrade catcode

Standalone downloads

Installers, standalone executables, MSI packages, DMG images, and AppImages are also available from the GitHub Releases page.

Quick start

Open a terminal inside the project you want CatCode to work on:

cd /path/to/your/project
catcode

Once CatCode opens:

  1. Run /login and select a provider.
  2. Run /model and select a model.
  3. Describe what you want the agent to do.

Example:

Review this project, explain how it is structured, and identify the most important bugs to fix.

CatCode uses the directory where it was launched as the workspace. File operations are confined to that workspace unless you explicitly change the configuration.

Essential commands

Command Description
/login Add or select a model provider
/model View and switch models
/approval Configure when tool actions require approval
/settings Open CatCode settings
/goal Start a larger planned task using multiple agents
/help Display all available commands

You can also run shell commands directly from the terminal interface:

!git status

Use two exclamation marks when you do not want the command output added to the model context:

!!clear

Providers

CatCode includes provider presets and supports additional providers through plugins.

Built-in presets currently include:

  • Umans
  • OpenCode Go
  • OpenRouter
  • DeepSeek

You can also connect compatible local servers, gateways, and custom endpoints. Use /login inside CatCode to configure a provider.

Environment variables may be used for API keys so secrets do not need to be entered into the interface.

Safety

CatCode provides several layers of protection while an agent works:

  • Workspace path confinement
  • Approval prompts for destructive tools
  • Restricted-path protection
  • Filesystem checkpoints
  • Optional operating-system sandboxing
  • Tool and session logs
  • Configurable network access

The default approval mode asks before destructive operations. Review commands and file changes before approving them, especially when working in an important repository.

Updating

Update the terminal application with:

catcode --update

When the browser frontend was installed through the CatCode installer, the update command also refreshes its installed components and restarts the service.

Updates can also be started from:

Settings → About → Update CLI + frontend

Uninstall

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/catalystctl/catcode/refs/heads/master/install.sh \
  | bash -s -- --uninstall

Windows

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/catalystctl/catcode/refs/heads/master/install.ps1))) -Uninstall

Homebrew

brew uninstall catcode

Documentation

More detailed guides are available in the CatCode documentation, including:

  • Installation and configuration
  • Commands and keyboard controls
  • Model providers
  • Tools and approval rules
  • Subagents and goal mode
  • Memory and skills
  • Plugins and custom tools
  • Browser frontend deployment
  • Architecture and development

Contributing

Contributions, bug reports, and feature requests are welcome.

Development and build instructions are available in the contributor documentation.

License

Catalyst Code is distributed under the MIT License.