excergic-token 0.1.0

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 OpenAI — 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

# Set your OpenAI API key
export OPENAI_API_KEY=sk-your-key-here

# Start the agent in your project directory
token chat --workspace .

You can also create a .env file in your project:

OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o

Usage

# Interactive chat (default)
token
token chat

# Options
token chat --model gpt-4o-mini --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 LLM — provider abstraction with OpenAI as the default
• Colorful UI — Rich panels, markdown, syntax highlighting, spinners

Slash commands

Command	Description
/help	Show help
/clear	Clear conversation history
/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

Environment variables (via .env or shell):

Variable	Default	Description
OPENAI_API_KEY	—	Your OpenAI API key
OPENAI_MODEL	gpt-4o	Model to use
LLM_PROVIDER	openai	LLM provider (extensible)
WORKSPACE_ROOT	.	Sandbox workspace root

Development

git clone https://github.com/Excergic/Token.git
cd Token
uv sync
cp .env.example .env   # add your API key
uv run token chat --workspace .

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 v0.1.0
git push origin v0.1.0
# Create a GitHub Release from the tag — CI publishes automatically

Manual publish:

uv build
UV_PUBLISH_TOKEN=pypi-... uv publish

License

MIT