Metadata-Version: 2.4
Name: excergic-token
Version: 2.0.0
Summary: Token — model-independent CLI coding agent with PEV architecture, MVP deployment, and audience-adaptive output
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/)

A model-independent CLI coding agent. Works for everyone — developers, founders, designers, PMs — and ships MVPs to production from the terminal.

## What's new in v2

v2 is a ground-up rewrite of the core architecture. The single-loop foundation stays; everything around it was redesigned for model independence and non-developer usability.

### v1 → v2 at a glance

| | v1 | v2 |
|---|---|---|
| **Architecture** | Single free-form loop | Planner-Executor-Verifier (PEV) + free-form fallback |
| **Model dependence** | Good results require a capable model | Cheap models get the same trajectory — harness carries the intelligence |
| **Who it's for** | Developers only | Anyone: non-tech founders, designers, PMs, devs |
| **Deployment** | Manual (user runs CLI commands) | First-class: one-command deploy to Vercel, Railway, Fly, Netlify |
| **Database** | Not supported | Supabase setup built in |
| **Goal tracking** | Lost on context compression | TaskPlan pinned into every system prompt — never compressed away |
| **Step verification** | Model self-reports done | MachineVerifier checks exit codes, files, env vars, HTTP status |
| **Output** | Raw technical output | Audience-adaptive: plain English / semi-tech / developer modes |
| **Provider support** | OpenAI only | OpenAI, Anthropic, Google Gemini, OpenRouter |
| **Guardrails** | Warn only | Hard stops enabled by default |
| **Memory** | Session-scoped | Persistent across sessions (MEMORY.md + USER.md) |
| **Observability** | None | LangSmith + Langfuse tracing, per-session tool logs |
| **Tests** | None | 46 unit tests covering PEV core, verifier, response translator |

### v2 in detail

**Planner-Executor-Verifier (PEV) architecture**

On the first turn, Token detects your expertise level and intent (BUILD / DEPLOY / FIX / EXPLAIN), then generates a 3–6 step structured TaskPlan. Each step is executed in a bounded tool loop, then verified by `MachineVerifier` (deterministic — checks exit codes, file existence, HTTP status) before advancing. The LLM only handles the narrow job of each layer: profiling, planning, executing, verifying. This is why cheap models work.

**TaskPlan pinned into every system prompt**

The full task plan — goal, step list, current step, error history — is injected fresh into every system prompt as a non-compressible block. Even after context compression, the model always knows what it's doing and which step it's on.

**First-class MVP deployment**

Five deployment tools built in: `deploy_vercel`, `deploy_railway`, `deploy_fly`, `deploy_netlify`, `setup_supabase`. Each includes auto-detection, prerequisite checks, exact CLI commands from a knowledge base, and URL verification after deploy. Non-tech users just say "deploy this" — Token handles the rest.

**Audience-adaptive output**

Responses are tailored to three tiers:
- **Non-tech** — plain English, live URL first, no jargon, "what's next" prompt
- **Semi-tech** — outcome + filtered step results, no stack traces
- **Developer** — full output, artifacts, diffs, step results

**Multi-provider support**

Switch between OpenAI, Anthropic (Claude), Google Gemini, and OpenRouter mid-session with `/provider`. Model catalog fetched live from each provider.

---

## Install

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

Or with pip / uv:

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

Requires **Python 3.11+**.

## Quick start

```bash
token
```

First run prompts for your API key and model. Credentials saved to `~/.config/token/config.json` (mode `0600`). Workspace defaults to the current directory.

## Usage

```bash
# Start the agent
token

# Optional flags
token --model gpt-4o --workspace /path/to/project

# Version
token version
```

## How it works

```
You type a goal
  -> UserProfiler detects expertise + intent (one LLM call)
  -> Planner builds 3-6 step TaskPlan (one LLM call, JSON schema)
     -> DeploymentKB + TemplateLibrary inject exact CLI commands
  -> TaskPlan pinned into every system prompt (never compressed away)
  -> PEV loop for each step:
       -> Executor: bounded tool loop until model returns text
       -> MachineVerifier: exit_code, file_exists, http_status (no LLM)
       -> LLMVerifier: only if machine check is inconclusive
       -> RetryManager: retry / fallback / escalate
  -> ResponseTranslator: formats completion for audience tier
```

For explain/fix/refactor — no plan needed — falls back to the v1 free-form loop.

## Tools

### Workspace

| Tool | Permission | Description |
|------|-----------|-------------|
| `get_project_tree` | auto | Full recursive file map |
| `read_file` | auto | Read file contents |
| `list_directory` | auto | List files in a directory |
| `search_in_files` | auto | Regex search across workspace |
| `write_file` | ask | Overwrite a file |
| `create_file` | ask | Create a new file |
| `run_command` | ask | Run a shell command |

### Deployment

| Tool | Permission | Description |
|------|-----------|-------------|
| `deploy_vercel` | ask | Deploy to Vercel, returns live URL |
| `deploy_railway` | ask | Deploy to Railway (backends, full-stack) |
| `deploy_fly` | ask | Deploy to Fly.io (Docker-based, global edge) |
| `deploy_netlify` | ask | Deploy static sites to Netlify |
| `setup_supabase` | ask | Create a Supabase database project |

### Environment and Web

| Tool | Permission | Description |
|------|-----------|-------------|
| `check_env_vars` | auto | Check which env vars are set vs missing |
| `set_env_var` | ask | Add/update a variable in .env |
| `list_env_file` | auto | List .env variable names (values masked) |
| `fetch_docs` | auto | Fetch a URL and return readable text |
| `check_url` | auto | Verify a deployed URL is live |

Read-only tools run concurrently. Write and deploy tools require explicit approval.

## Slash commands

| Command | Description |
|---------|-------------|
| `/plan` | Show current task plan and step status |
| `/profile` | Show detected user profile (expertise, stack, deploy target) |
| `/clear` | Clear conversation history and task plan |
| `/usage` | Show token usage for this session |
| `/insights` | Session analytics: tools, guardrails, memory |
| `/memory` | Show persistent memory contents |
| `/provider` | Switch provider and model mid-chat |
| `/setup` | Re-run provider and model setup |
| `/help` | Show help |
| `/exit` | Quit |

## Context management

- **Token budget** — 80% of the model's context window. Exits cleanly when exhausted.
- **Three-stage compression** — before first call (estimated), before every call (real token count), after tool execution. Protects first message and last 6. Summarises middle via auxiliary LLM.
- **TaskPlan pinned** — task state is injected into the system prompt each turn, not conversation history. Never compressed away.

## Permission prompts

When the agent wants to write a file, run a command, or deploy, you'll see a preview and be asked:

- **y** — allow once
- **a** — allow all for this session
- **n** — deny

## Configuration

API keys are saved to `~/.config/token/config.json` (mode `0600`) — never to `.env`.

Optional environment variables:

| 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
uv run token
```

Run tests:

```bash
uv run pytest tests/ -v
```

## Publishing (maintainers)

Releases are published to PyPI as [`excergic-token`](https://pypi.org/project/excergic-token/).

```bash
git tag v2.0.0
git push origin v2.0.0
# Create a GitHub Release — CI publishes automatically
```

Manual publish:

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

## License

MIT
