Claude Free

A CLI for running Claude Code with a local OmniRoute service.

It starts OmniRoute when needed, keeps configuration in one place, and launches claude with the saved settings.

Why use this?

• avoids repeating OmniRoute setup every session
• keeps API key, model, and port in ~/.config/claude-free/config.json
• gives one command for status, logs, repair, and restart
• works with the installed claude and omniroute binaries

Features

• start OmniRoute and launch Claude Code
• inspect runtime state with --status
• run environment checks with --doctor
• repair installation state and shell integration with --repair
• update model, API key, and port from the CLI
• pass arguments directly to Claude Code with --

Installation

npm

npm install -g claude-free

From source

git clone https://github.com/ayush/claude-free.git
cd claude-free
./install.sh

Requirements

The CLI requires these commands:

• jq
• curl
• omniroute
• claude

Install them before first use.

Quick Start

claude-free --help
claude-free --doctor
claude-free --start
claude-free --status

Configuration

The CLI stores its configuration in ~/.config/claude-free/config.json.

You can also create an optional ~/.config/claude-free/.env file to seed values such as:

ANTHROPIC_API_KEY=your-key
CLAUDE_FREE_MODEL=auto
CLAUDE_FREE_PORT=20128

Commands

Command	Description
claude-free	Start OmniRoute and launch Claude Code
claude-free --help	Show the CLI help output
claude-free --version	Show the installed CLI version
claude-free --status	Show OmniRoute and runtime status
claude-free --doctor	Run environment diagnostics
claude-free --logs	Tail the OmniRoute log
claude-free --start	Start OmniRoute only
claude-free --restart	Restart OmniRoute
claude-free --stop	Stop OmniRoute
claude-free --new	Recreate runtime data and restart
claude-free --reset	Reset local state and reconfigure
claude-free --config	Print the current config
claude-free --model	Change the active model
claude-free --apikey	Update the API key
claude-free --port	Change the OmniRoute port
claude-free --repair	Repair installation and shell integration
claude-free --install	Install or repair the CLI
claude-free --uninstall	Remove the CLI and its integration

Examples

Start the local workflow:

claude-free

Check service state:

claude-free --status

Repair shell integration:

claude-free --repair

Pass arguments directly to Claude Code:

claude-free -- --continue

Troubleshooting

Problem	Fix
claude-free is not found	Reopen the shell or source your shell rc file
Missing dependencies	Install jq, curl, omniroute, and claude
OmniRoute does not respond	Run claude-free --doctor and claude-free --restart

FAQ

Does this change my Claude Code install?

No. It uses the existing claude CLI and OmniRoute service.

Where is config stored?

In ~/.config/claude-free/config.json.

How do I change the port?

Run claude-free --port <port>.

Development

bash -n claude-free install.sh uninstall.sh
npm test

Contributing

Open an issue or submit a pull request with a clear summary of the change.

License

MIT