Metadata-Version: 2.4
Name: excergic-token
Version: 0.1.3
Summary: Token — a colorful CLI coding agent with file tools, shell execution, and swappable LLM providers
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: langgraph>=1.2.7
Requires-Dist: langgraph-checkpoint-sqlite>=3.1.0
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: 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 OpenAI — 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 asks for your OpenAI API key and model, saves them to `~/.config/token/`, then opens the chat. Workspace defaults to your current directory.

```bash
# Optional: override via environment
export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=gpt-4.1

token
```

## Usage

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

# Optional flags
token --model gpt-4.1-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 |
| `/setup` | Update API key and model   |
| `/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

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

Manual publish:

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

## License

MIT
