excergic-token 1.2.3

Token — a colorful CLI coding agent with file tools, shell execution, and OpenAI

Token

The problem

Most AI coding tools are either cloud-hosted editors you can't control, or heavyweight frameworks that bury a simple idea under layers of abstraction. You want an agent that reads your code, makes changes, and runs commands — right in your terminal, powered by OpenAI, without handing your codebase to a third-party service.

Existing open-source agents often use complex multi-agent graphs with routing nodes, sub-agent spawning, and checkpoint systems. This adds latency, makes debugging harder, and burns tokens on orchestration overhead instead of actual coding work.

How Token solves it

Token is a single-loop coding agent. One LLM conversation, one while loop — the model decides what tools to call and keeps going until it has an answer. No multi-agent graphs, no routing nodes, no sub-agent spawning.

• Single conversation loop — the LLM calls tools (read files, write files, run commands) until it returns a text response. No orchestration layer between you and the model.
• Three-stage compression — automatically compresses conversation history when it approaches 75% of the context window, so long sessions don't crash or lose context.
• Read/write parallelization — read-only tool calls (file reads, searches, tree listings) run concurrently. Write operations run sequentially with human approval.
• OpenAI — live model catalog from the OpenAI API. Paste your key, pick a model, start coding.
• Workspace sandbox — all file operations are confined to your project directory. Nothing touches files outside the workspace root.

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 your OpenAI API key, 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 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

How it works

Token runs a Hermes-style conversation loop:

You type a query
  -> Three-tier system prompt (stable + context + volatile)
  -> LOOP:
       -> Compress if approaching context limit
       -> Sanitize messages
       -> LLM API call (with bound tools)
       -> If tool calls: execute (parallel reads / sequential writes) -> loop back
       -> If no tool calls: display text response -> done

The LLM sees your workspace structure, git status, and project instructions in the system prompt. It decides which tools to call — there's no routing logic, no planner node, no verifier. The model is the orchestrator.

Tools

Tool	Permission	Parallel
get_project_tree	auto	yes
read_file	auto	yes
list_directory	auto	yes
search_in_files	auto	yes
write_file	ask	no
create_file	ask	no
run_command	ask	no

Read-only tools run concurrently via ThreadPoolExecutor. Write tools run one at a time with a permission gate preview.

Context management

• Token budget — 80% of the model's context window. Loop exits when exhausted.
• Three-stage compression — checks before first call (estimated), before every call (real token count), and after tool execution. Protects the first message (user intent) and last 6 messages (recent context), summarizes the middle via a cheap auxiliary LLM.

Slash commands

Command	Description
/help	Show help
/clear	Clear conversation history
/provider	Switch OpenAI model or API key
/setup	Re-run OpenAI key 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	300	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.2.2
git push origin v1.2.2
# Create a GitHub Release from the tag — CI publishes automatically

Manual publish:

uv build
UV_PUBLISH_TOKEN=pypi-... uv publish

License

MIT