Metadata-Version: 2.4
Name: uv-agent
Version: 0.11.4
Summary: Experimental Python-runner coding agent with a Textual TUI
Project-URL: Repository, https://github.com/4fuu/uv-agent
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: anthropic>=0.103.1
Requires-Dist: mcp>=1.27.1
Requires-Dist: openai>=2.36.0
Requires-Dist: pillow>=12.0.0
Requires-Dist: pluggy>=1.6.0
Requires-Dist: pygments>=2.20.0
Requires-Dist: textual-image[textual]>=0.12.0
Requires-Dist: textual>=6.5.0
Requires-Dist: tomlkit>=0.15.0
Requires-Dist: tree-sitter-language-pack>=1.8.1
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: unidiff>=0.7.5
Requires-Dist: watchfiles>=1.1.1
Description-Content-Type: text/markdown

# uv-agent

<img align="right" src="docs/t1.png" alt="uv-agent TUI screenshot" width="300">

[简体中文](README.zh-CN.md)

`uv-agent` is a Windows-first coding agent with a Textual TUI. It is designed
around one external action surface: `run_python`. The model writes managed Python
scripts, uv-agent runs them through `uv run`, and the runtime exposes focused
helpers for editing files, running commands, searching code, using MCP, launching
subagents, and attaching images.

That single boundary keeps coding-agent work easier to inspect, replay, interrupt,
and compact during long sessions. The design also makes it easy to port to any
Python and uv environment. The project is still experimental, so public APIs,
config fields, and runtime behavior may change.

## Why uv-agent?

- **Windows-first coding UI.** A Textual transcript with a multi-line composer,
  command palette, model/tool timeline, file and thread mentions, image
  attachments, and English or Chinese UI.
- **One action boundary.** No direct shell, filesystem, browser, or MCP model
  tools; external work flows through managed Python runs and one persistent event
  stream.
- **Long-task friendly.** Checkpoint compaction, workspace rules, skills, MCP
  declarations, Goal state, and Worktree state are replayed as structured context
  when needed.
- **Practical coding workflows.** `/goal` adds lightweight per-thread
  checklist/notes for longer tasks; Worktree mode creates an isolated Git branch
  worktree for task-focused changes.
- **Extensible runtime.** Plugins can add `uv_agent_runtime` helpers, subscribe
  to agent events, and submit turns from external systems without adding extra
  model-visible tools.

## Quick Start

Install the required tools:

- **uv** — https://docs.astral.sh/uv/getting-started/installation/
- **ripgrep** — https://github.com/BurntSushi/ripgrep#installation
- **Git** — needed for normal coding workflows and Worktree mode.

Run the latest published package:

```powershell
uvx uv-agent@latest
```

Run from a local checkout:

```powershell
uv run uv-agent
```

Ask a single prompt without opening the TUI:

```powershell
uvx uv-agent@latest ask "Reply with exactly: ok"
```

Resume an existing thread:

```powershell
uvx uv-agent@latest ask --thread thr_xxx "Continue from here"
```

## Model Configuration

uv-agent does not ship a real provider configuration. Configure at least one
provider, model, and level before making model calls.

Config is loaded from `~/.uv-agent/config.json`, then optional project overrides
from `.uv-agent/config.json`. The project-local `.uv-agent/` directory is ignored
by git. Prefer environment variables or ignored local config for API keys.

Supported model API formats:

| `api` value | Format |
| --- | --- |
| `"responses"` | OpenAI Responses API |
| `"chat_completions"` | OpenAI Chat Completions API |
| `"anthropic_messages"` | Anthropic Messages API |

<details>
<summary>Full configuration example</summary>

```json
{
  "providers": {
    "deepseek": {
      "base_url": "https://api.deepseek.com",
      "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "chat_completions": {
        "path": "/chat/completions"
      },
      "message_passthrough": {
        "assistant": [
          "reasoning_content"
        ]
      },
      "reasoning_display": {
        "assistant_message_fields": [
          "reasoning_content"
        ],
        "stream_delta_fields": [
          "reasoning_content"
        ]
      }
    },
    "minimax": {
      "base_url": "https://api.minimaxi.com",
      "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "chat_completions": {
        "path": "/v1/chat/completions"
      },
      "anthropic_messages": {
        "path": "/anthropic/v1/messages"
      }
    }
  },
  "models": {
    "deepseek-v4-flash": {
      "provider": "deepseek",
      "model": "deepseek-v4-flash",
      "api": "chat_completions",
      "supports_images": false,
      "context_window_tokens": 1000000,
      "params": {
        "reasoning_effort": "high"
      }
    },
    "deepseek-v4-pro": {
      "provider": "deepseek",
      "model": "deepseek-v4-pro",
      "api": "chat_completions",
      "supports_images": false,
      "context_window_tokens": 1000000,
      "params": {
        "reasoning_effort": "max"
      }
    },
    "MiniMax-M2.7": {
      "provider": "minimax",
      "model": "MiniMax-M2.7-highspeed",
      "api": "anthropic_messages",
      "supports_images": false,
      "context_window_tokens": 204800
    }
  },
  "levels": {
    "deepseek-flash": {
      "model": "deepseek-v4-flash"
    },
    "deepseek-pro": {
      "model": "deepseek-v4-pro"
    },
    "MiniMax-M2.7": {
      "model": "MiniMax-M2.7"
    }
  },
  "runtime": {
    "default_level": "deepseek-flash",
    "ask_default_level": "deepseek-flash",
    "store_provider_response": false,
    "max_agent_rounds": 1000,
    "compression": {
      "enabled": true,
      "model_level": "deepseek-flash",
      "trigger_ratio": 0.9
    },
    "title_generation": {
      "enabled": true,
      "model_level": "deepseek-flash"
    }
  },
  "runner": {
    "default_timeout_s": 7200,
    "max_output_bytes": 1000000
  },
  "pricing": {
    "currency": "RMB",
    "unit": "1M_tokens",
    "models": {
      "deepseek-v4-flash": {
        "input": 1,
        "output": 2,
        "cached_input": 0.02
      },
      "deepseek-v4-pro": {
        "input": 3,
        "output": 6,
        "cached_input": 0.025
      }
    }
  },
  "ui": {
    "completion_notification": {
      "enabled": true
    }
  },
  "plugins": {
    "disabled": [],
    "config": {}
  }
}

```

</details>

Use `/config` in the TUI to switch user-facing settings such as default level,
language, completion notification, and automatic compression. See
[configuration](docs/configuration.md) for every supported option and
[config.example.json](docs/config.example.json) for a detailed standalone example.

## Everyday Workflow

- `Ctrl+Enter` or `Ctrl+J` sends the composer; `Enter` inserts a newline.
- `/` from an empty composer or `Ctrl+O` opens the command palette.
- `@` inserts file mentions, `@@` inserts thread mentions, and `/threads` resumes
  past work.
- `/goal` toggles durable checklist/notes for the current thread.
- **Worktree** in the command palette creates or manages a task worktree under
  `.uv-agent/worktrees/`.
- `F2` attaches a clipboard image; `F3` previews pending images.
- `/status`, `/models`, `/level`, `/mcp`, and `/skills` inspect runtime state and
  available capabilities.

See [TUI and slash commands](docs/tui.md) for the full command and shortcut list.

## Plugins

Plugins are normal Python packages discovered through the `uv_agent.plugins`
entry point group. They run in the uv-agent host process and can register runtime
helpers, subscribe to events, or submit turns from external systems.

For a one-off run with an extra plugin package, add it beside the app launched by
`uvx`:

```powershell
uvx --with your-uv-agent-plugin uv-agent@latest
```

Disable installed plugins with `plugins.disabled` in config. See
[Plugin system](docs/plugins.md) for the plugin API, event bus, helper
registration, and examples.

## Runtime And Context

Every model-visible turn is built from a stable system prompt plus replayable
pre-user context items. The system prompt stays compact and rarely changes;
project and runtime details are delivered as structured messages immediately
before the user turn.

- **Managed runtime.** `run_python` is the only external action surface. Managed
  scripts run in the project-shared uv environment at
  `~/.uv-agent/projects/<project-id>/runner/scriptenv/` and import
  `uv_agent_runtime` helpers for file edits, search, subprocesses, dependency
  installation, subagents, image context, MCP clients, plugin helpers, and more.
  The script uv environment and the active working directory are separate; the
  cwd can move with `enter_dir` or Worktree mode.
- **Incremental runtime context.** Runtime environment, model levels, helper
  lists, direct script-environment dependencies, skills, MCP servers, and plugin
  helpers are split into fingerprinted context parts. uv-agent sends only
  changed parts inside `<context_update ...>` envelopes and explicitly marks
  removed skills or MCP servers so the model does not rely on stale capabilities.
- **Workspace and thread context.** Workspace rules are disclosed progressively:
  the model first receives a rule index, then full AGENTS.md content when it
  enters a relevant directory. Active cwd changes, image attachments, Worktree
  notices, tool results, run logs, and thread metadata are persisted in the same
  event stream and replayed when reconstructing a turn.
- **Goal mode durable memory.** `/goal` adds a per-thread memory layer under
  `~/.uv-agent/projects/<project-id>/goals/<thread-id>/` with `goal.json`,
  `checklist.md`, and `notes.md`. When Goal mode is active, uv-agent replays a
  `<goal_mode>` notice containing those paths and maintenance rules. The model
  uses `checklist.md` for acceptance criteria, progress, blockers, and next
  steps, and `notes.md` for decisions, investigation notes, constraints, and
  handoff context. The `goal_paths()` runtime helper lets managed scripts find
  those files without hard-coding paths.
- **Compaction and resume.** Checkpoint compaction summarizes the conversation
  while excluding reloadable runtime context, workspace rules, Goal notices, and
  Worktree notices from retained history. A new epoch replays current structured
  context before retained history, and Goal files remain the preferred source for
  long-running task progress after compaction or resume.

Thread state, run logs, shared script dependencies, attachments, Goal files, and
other project runtime data live under `~/.uv-agent/projects/<project-id>/`.

## Documentation

- [Configuration](docs/configuration.md)
- [Full config example](docs/config.example.json)
- [TUI and slash commands](docs/tui.md)
- [Runtime and managed scripts](docs/runtime.md)
- [Plugin system](docs/plugins.md)

## Development

uv-agent is developed in a self-bootstrapping style: the project is routinely
read, edited, tested, and refined with uv-agent itself.

```powershell
uv run pytest
```

Local debug state, screenshots, config, scripts, runs, and thread data belong in
`.uv-agent/` and should stay out of git.

## License

MIT. See [LICENSE](LICENSE).
