excergic-token 1.1.3

Token — a colorful CLI coding agent with file tools, shell execution, and swappable LLM providers

Token

A colorful CLI coding agent built in Python. It reads and writes files, searches code, runs shell commands, and chats with you via OpenRouter, OpenAI, Anthropic, or Google — all from your terminal with a Rich-powered UI.

Install

Recommended — isolated CLI install with pipx:

pipx install excergic-token

Or with pip:

pip install excergic-token

Or with uv:

uv tool install excergic-token

Requires Python 3.11+.

Quick start

pipx install excergic-token
token

On first run, Token prompts you to paste an API key in the terminal, fetches models live, and saves your credentials to ~/.config/token/config.json (mode 0600, only your user can read it). Workspace defaults to your current directory.

token

Use /provider anytime to switch provider, paste a new key, or pick a different model.

Usage

# Start the agent (default — uses current directory as workspace)
token

# Optional flags
token --model gpt-4o --workspace /path/to/project

# Version
token version

Features

• File tools — read, write, create, list directories, regex search
• Shell execution — run commands in your workspace (with permission)
• Human-in-the-loop — destructive actions require explicit approval (y / a / n)
• Workspace sandbox — all paths confined to a configurable root
• Swappable LLMs — OpenRouter, OpenAI, Anthropic, or Google with live model catalogs
• Colorful UI — Rich panels, markdown, syntax highlighting, spinners

Slash commands

Command	Description
/help	Show help
/clear	Clear conversation history
/provider	Switch provider and model mid-chat
/setup	Re-run provider and model setup
/usage	Show session token usage
/exit	Quit

Permission prompts

When the agent wants to write a file or run a shell command, you'll see a preview and be asked:

• y — allow once
• a — allow all for this session
• n — deny

Configuration

API keys are never read from .env. Paste them in the CLI during setup (/setup or /provider); they are saved to ~/.config/token/config.json.

Optional environment variables (non-secret tuning only):

Variable	Default	Description
WORKSPACE_ROOT	.	Sandbox workspace root
SHELL_TIMEOUT_SECONDS	60	Shell command timeout
TOKEN_BUDGET_LIMIT	200000	Per-session token budget

Development

git clone https://github.com/Excergic/Token.git
cd Token
uv sync
cp .env.example .env   # optional workspace overrides only
uv run token

Publishing (maintainers)

Releases are published to PyPI as excergic-token via GitHub Actions when a GitHub Release is published.

1. Configure PyPI Trusted Publishing for excergic-token → GitHub Excergic/Token
2. Create a GitHub environment named pypi in repo settings
3. Tag and release:

git tag v1.1.3
git push origin v1.1.3
# Create a GitHub Release from the tag — CI publishes automatically

Manual publish:

uv build
UV_PUBLISH_TOKEN=pypi-... uv publish

License

MIT