Metadata-Version: 2.4
Name: excergic-token
Version: 1.1.3
Summary: Token — a colorful CLI coding agent with file tools, shell execution, and swappable LLM providers
Keywords: cli,coding-agent,llm,openrouter,openai,anthropic,google,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-anthropic>=0.3.0
Requires-Dist: langchain-core>=1.4.8
Requires-Dist: langchain-google-genai>=2.1.0
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/)

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:**

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

```bash
token
```

Use `/provider` anytime to switch provider, 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
```

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

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

Manual publish:

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

## License

MIT
