Metadata-Version: 2.5
Name: deltaa
Version: 0.2.2
Summary: A minimal coding agent harness in Python, inspired by pi (TypeScript).
Project-URL: Homepage, https://github.com/kartikg-gk/delta
Project-URL: Repository, https://github.com/kartikg-gk/delta
Project-URL: Issues, https://github.com/kartikg-gk/delta/issues
Author: Kartik G
License-Expression: MIT
License-File: LICENSE
Keywords: agent,cli,coding-agent,llm,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: httpx[socks]>=0.27
Requires-Dist: pydantic>=2.7
Requires-Dist: textual>=8.2.8
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/kartikg-gk/delta/main/assets/delta-logo.png" alt="Delta" width="420">
</p>

<p align="center">
  <a href="https://pypi.org/project/deltaa/"><img src="https://img.shields.io/pypi/v/deltaa?label=pypi&color=7c6cf0" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-3.12%2B-5b8def" alt="Python 3.12+">
  <a href="https://github.com/kartikg-gk/delta/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-2b2d31" alt="MIT license"></a>
  <img src="https://img.shields.io/badge/models-OpenAI%20%C2%B7%20Anthropic%20%C2%B7%20OpenRouter%20%C2%B7%20Ollama%20%C2%B7%20Hugging%20Face-3a3d4a" alt="Providers">
</p>

<p align="center">
  <a href="#install">Install</a> ·
  <a href="#quickstart">Quickstart</a> ·
  <a href="#providers-and-configuration">Providers</a> ·
  <a href="#commands">Commands</a> ·
  <a href="#project-structure">Architecture</a>
</p>

Delta is a minimal coding agent harness in Python built around a small, inspectable model–tool loop. It provides filesystem and shell tools, multi-provider model support, customizable tools, skills, prompts and hooks, and clean interfaces for extending agent behavior without changing the core runtime. Delta can be used interactively from the terminal, scripted for one-shot tasks, or embedded into larger agent and evaluation workflows.
Requires Python 3.12 or newer.

<p align="center">
  <img src="https://raw.githubusercontent.com/kartikg-gk/delta/main/assets/cli.png" alt="Delta's terminal UI fixing a failing test: it reads calc.py, edits it, runs the test, and reports the fix" width="900">
</p>

## Install

The package name on PyPI is `deltaa`; once installed it gives you a `delta` command.

Fastest path — one script, works on a machine with nothing set up yet:

macOS / Linux:

```bash
curl -LsSf https://raw.githubusercontent.com/kartikg-gk/delta/main/scripts/install.sh | sh
```

Windows (PowerShell):

```powershell
irm https://raw.githubusercontent.com/kartikg-gk/delta/main/scripts/install.ps1 | iex
```

No admin/root privileges needed. If `uv` isn't found on your machine, the script
grabs it first, then puts Delta in its own isolated environment and runs
`delta --version` at the end so you know it worked. Read either script under
[`scripts/`](scripts/) before running it if you'd rather not pipe-to-shell blind.

If you already manage Python packages some other way, pick one:

```bash
uv tool install deltaa      # isolated, recommended if you have uv
pipx install deltaa         # isolated, no uv needed
python -m pip install deltaa
```

Confirm it landed:

```bash
delta --version
```

When a new version ships:

```bash
uv tool upgrade deltaa
```

## Quickstart

Delta needs a model provider. Set one up once:

```bash
delta config
```

Now `cd` into whatever project you want it working on and launch it:

```bash
cd my-project
delta
```

With no arguments, `delta` drops you into the terminal UI — start typing and hit
Enter, same as any chat interface:

```
what does the auth module in this repo do?
```

Need it non-interactively instead — for a script, a Makefile target, CI, whatever —
pass `-p` and it prints the answer and exits:

```bash
delta -p "list every route this API exposes"
delta --model gpt-5 -p "where is the retry logic for failed requests?"
```

If you'd rather stay in a plain scrolling terminal than the full-screen UI:

```bash
delta --repl
```

## Providers and configuration

Built-in providers: **OpenAI**, **Anthropic**, **OpenRouter**, and **Ollama** for local
models.

`delta config` walks you through picking a provider, a model, and an API key. It can
also run without prompts:

```bash
delta config --provider openai --model gpt-5
delta config show        # saved settings, keys masked
delta config path        # where the file lives
```

Settings are stored in `~/.delta/config.toml`, outside your project, with owner-only
permissions. Environment variables take priority over the file:

| Variable | Purpose |
|---|---|
| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `OPENROUTER_API_KEY` | Provider credentials |
| `DELTA_API_KEY` | API key for `delta config` without an interactive prompt |
| `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` | Point a provider at another compatible endpoint |
| `DELTA_PROVIDER` / `DELTA_MODEL` | Force the active provider or model |
| `DELTA_HOME` | Move `~/.delta` (sessions, logs, skills, prompts, extensions) |
| `DELTA_CONFIG_DIR` | Move the config file |

Inside a session, `/model` and `/provider` switch on the fly.

## Commands

From your shell:

```bash
delta [prompt]                           # terminal UI, or a one-shot prompt
delta -p "..."                           # print mode: stream the answer, then exit
delta -r <session-id>                    # resume a saved session
delta config [show|path]                 # provider setup
delta provider list|setup|select <name>  # inspect or switch providers
delta session list                       # saved sessions
delta session export <id> [-f text|json|jsonl]
delta session stats [id]                 # token and cost totals
```

Useful flags: `--model/-m`, `--provider`, `--system-prompt`, `--max-turns`,
`--session-dir`, `--no-session`, `--repl`, `--verbose/-v`.

Inside a session, slash commands give live control:

| Area | Commands |
|---|---|
| Session | `/name` `/continue` `/export` `/stats` |
| History | `/compact` `/branch` `/branches` `/rewind` |
| Model | `/model` `/provider` `/think` `/plan` |
| Workspace | `/shell` `/skills` `/create-skill` `/reload` |
| Info | `/help` `/version` `/diag` `/quit` |

The terminal UI also has `/new` and `/session` for starting and switching sessions.

## Skills, prompts, and extensions

**Project instructions.** Delta reads `AGENTS.md` from, in increasing priority:
`~/.delta/`, `~/.agents/`, `<project>/.delta/`, `<project>/.agents/`, and the project
root. All files found are combined.

**Skills** are markdown instructions the agent can pull in when relevant. Put one at
`<project>/.delta/skills/<name>/SKILL.md` (or under `.agents/skills/`, or the same
paths in your home directory), list them with `/skills`, and invoke one directly with
`/skill:<name> [args]`. `/create-skill <name> <text>` writes a new one for you.

**Prompt templates** live in `.delta/prompts/` (project or home). Run one by typing
`/<template-name>`.

**Extensions** add capabilities without a restart: drop a `.py` file that defines a
`register` function into `~/.delta/extensions/` or `<project>/.delta/extensions/`,
then run `/reload`.

## Project structure

```mermaid
flowchart LR
    subgraph you["You"]
        tui["Terminal UI"]
        print["delta -p #quot;...#quot;"]
        repl["Line REPL"]
    end

    subgraph app["Session · delta_app"]
        session["Coding session<br/>slash commands · AGENTS.md<br/>skills · templates · extensions<br/>compaction · provider switching"]
    end

    subgraph harness["Agent loop · delta_harness"]
        loop["1. stream the model's reply<br/>2. run its tool calls<br/>3. send results back<br/>4. repeat until done"]
    end

    subgraph models["Models · delta_model"]
        anthropic["Anthropic adapter<br/>prompt caching · extended thinking"]
        compat["OpenAI-compatible adapter<br/>OpenAI · OpenRouter · Ollama<br/>Hugging Face · any compatible URL"]
    end

    tools["Tools<br/>Read · Write · Edit · Bash"]
    store[("Sessions<br/>~/.delta/sessions/*.jsonl")]

    tui --> session
    print --> session
    repl --> session
    session --> loop
    loop --> anthropic
    loop --> compat
    loop <--> tools
    session --> store
```

Three packages, layered so dependencies only point inward: `delta_harness` imports
neither of the others, `delta_model` imports the harness, and `delta_app` imports both.

```
src/
  delta_harness/          # core: the agent loop and its vocabulary
    contracts/            #   transcript entries, tool specs, event types, JSON values
    provider/             #   the model-provider interface and raw stream events
    session/              #   durable JSONL records, storage, replay, index, summaries
    engine.py             #   the agent loop
    driver.py             #   transcript-owning harness around the loop

  delta_model/            # providers: everything that talks to a model API
    claude.py  _claude/   #   Anthropic Messages API
    oai_compatible.py     #   OpenAI-compatible endpoints (OpenAI, OpenRouter, Ollama, ...)
    _oai/                 #   request building, response parsing, normalization, transport
    transport/            #   HTTP client, retry with backoff, error classification
    scripted.py           #   a deterministic fake provider for tests
    settings.py           #   environment-driven provider settings
    limits.py             #   context and output limits

  delta_app/              # application: the parts you actually use
    cli/                  #   entry point, argument parsing, `delta config`
    tui/                  #   terminal UI: transcript, composer, completions, pickers
    ui/render.py          #   headless output (plain, JSON, transcript)
    config/               #   config schema, TOML store, setup wizard, hidden key input
    tools/                #   file tools, shell tool, shared helpers
    runtime.py            #   session construction shared by every frontend
    conversation.py       #   the session object the CLI and UI both drive
    directives.py         #   slash-command registry and dispatch
    instructions.py       #   system-prompt assembly
    skillset.py           #   markdown skills
    prompts.py            #   prompt templates
    discovery.py          #   where skills, prompts, and sessions are found
    plugins.py            #   file-based extensions with hot reload
    refresh.py            #   `/reload` wiring
    context/budget.py     #   token accounting and compaction thresholds
    safety.py             #   tool approval and output scrubbing
    planning.py           #   plan mode
    reasoning.py          #   thinking modes
    sessions.py           #   create, resume, list, export
    logs.py               #   per-session run logs

tests/                    # one test module per concern
scripts/                  # install scripts
```

## Development

```bash
git clone https://github.com/kartikg-gk/delta.git
cd delta
uv sync
uv run delta --version
uv run pytest
uv run ruff check .
```

To point the global `delta` command at your checkout instead of a PyPI release:

```bash
uv tool install --editable --force .
```

Code changes in the checkout take effect right away with this setup. What doesn't
update on its own is the tool's dependency list and version metadata — those are
snapshotted at install time, so after pulling changes that touch `pyproject.toml`
(a new dependency, a version bump), rerun the command above to pick them up.

## License

MIT
