Metadata-Version: 2.4
Name: excergic-token
Version: 1.2.2
Summary: Token — a colorful CLI coding agent with file tools, shell execution, and OpenAI
Keywords: cli,coding-agent,llm,openai,ai-agent,terminal
Author: Excergic
Author-email: Excergic <dhaivat.jambudia@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: langchain-core>=1.4.8
Requires-Dist: langchain-openai>=1.3.3
Requires-Dist: openai>=2.44.0
Requires-Dist: pydantic-settings>=2.14.2
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: rich>=15.0.0
Requires-Dist: questionary>=2.1.0
Requires-Dist: typer>=0.26.8
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/Excergic/Token
Project-URL: Repository, https://github.com/Excergic/Token
Project-URL: Issues, https://github.com/Excergic/Token/issues
Project-URL: Documentation, https://github.com/Excergic/Token#readme
Description-Content-Type: text/markdown

# Token

[![PyPI version](https://img.shields.io/pypi/v/excergic-token)](https://pypi.org/project/excergic-token/)
[![Python](https://img.shields.io/pypi/pyversions/excergic-token)](https://pypi.org/project/excergic-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:**

```bash
pipx install excergic-token
```

**Or with pip:**

```bash
pip install excergic-token
```

**Or with uv:**

```bash
uv tool install excergic-token
```

Requires **Python 3.11+**.

## Quick start

```bash
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.

```bash
token
```

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

## Usage

```bash
# 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

```bash
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`](https://pypi.org/project/excergic-token/) via GitHub Actions when a GitHub Release is published.

1. Configure [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) for `excergic-token` → GitHub `Excergic/Token`
2. Create a GitHub environment named `pypi` in repo settings
3. Tag and release:

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

Manual publish:

```bash
uv build
UV_PUBLISH_TOKEN=pypi-... uv publish
```

## License

MIT
