{"id":50643124,"url":"https://github.com/4fuu/uv-agent","last_synced_at":"2026-06-07T10:01:37.116Z","repository":{"id":358408973,"uuid":"1240909104","full_name":"4fuu/uv-agent","owner":"4fuu","description":"Experimental coding agent with an ANSI-first terminal TUI and a single run_python action surface.","archived":false,"fork":false,"pushed_at":"2026-06-01T05:25:07.000Z","size":2484,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-01T07:17:04.889Z","etag":null,"topics":["ai-agent","ansi-tui","coding-agent","mcp","openai","python","python-runner","terminal-ui","tui","uv"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/4fuu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-16T18:11:08.000Z","updated_at":"2026-06-01T05:24:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/4fuu/uv-agent","commit_stats":null,"previous_names":["4fuu/uv-agent"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/4fuu/uv-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4fuu%2Fuv-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4fuu%2Fuv-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4fuu%2Fuv-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4fuu%2Fuv-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/4fuu","download_url":"https://codeload.github.com/4fuu/uv-agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4fuu%2Fuv-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34016490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ansi-tui","coding-agent","mcp","openai","python","python-runner","terminal-ui","tui","uv"],"created_at":"2026-06-07T10:01:36.411Z","updated_at":"2026-06-07T10:01:37.107Z","avatar_url":"https://github.com/4fuu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# uv-agent\n\n\u003cimg align=\"right\" src=\"docs/t2.png\" alt=\"uv-agent tui2 screenshot\" width=\"300\"\u003e\n\n[简体中文](README.zh-CN.md)\n\n**Python-native coding agent — one `run_python` boundary. Every external action is\nauditable, replayable, and interruptible.**\n\n`uv-agent` channels all model capabilities through a single, well-defined exit: the\nmodel can only touch the outside world via `run_python`. Each call is a complete\nPython script executed in a `uv run`-managed isolated environment, using\n`uv_agent_runtime` helpers for file editing, command execution, code search, MCP,\nsub-agents, images, and more. With only one exit, you can replay any run and see\nexactly what happened and why.\n\nThe project is still experimental. Public APIs, config fields, and runtime behavior\nmay change.\n\n## Features\n\n- **Single tool boundary** — no shell, filesystem, browser, or MCP model tools. The\n  model writes Python; the managed runtime executes it. Every external action is an\n  auditable script.\n- **Cache-aware NetGain compaction** — long conversations no longer trigger blind\n  compression. A pre-turn lightweight judge round lets the model estimate remaining\n  calls and history dependency, then computes the net gain of compaction via an\n  economic formula. Compression fires only when cache savings outweigh information\n  loss. Recent context is retained verbatim (K tokens) to avoid losing key details.\n- **Python managed runtime** — scripts run in a project-shared `uv` environment.\n  `uv_agent_runtime` provides helpers for read/write/edit, ripgrep search,\n  subprocesses, dependency installation, sub-agents, MCP clients, and more.\n  Scripts serve as documentation — no opaque shell commands.\n- **Plugin system** — plain Python packages discovered via `uv_agent.plugins` entry\n  point. Register runtime helpers, subscribe to events, submit turns from external\n  systems. `uvx --with your-plugin uv-agent` and you're set.\n- **Self-bootstrapping** — uv-agent is developed using uv-agent. Reading, editing,\n  testing, and iterating on the project are done with uv-agent itself.\n- **Progressive context disclosure** — skills, MCP servers, and workspace rules are\n  not dumped into the prompt all at once. The model receives an index first; full\n  content is disclosed only when needed. Removed capabilities are explicitly marked\n  to prevent stale-context errors.\n- **Goal mode durable memory** — `/goal` creates a per-thread checklist/notes layer\n  independent of the chat transcript. After compaction or resume, the model consults\n  Goal files rather than relying solely on summarized history.\n- **Agent View parallel workspaces** — dispatch bug investigations, implementation\n  experiments, and test fixes to isolated Git worktree background sessions. Track\n  them all from a single dashboard.\n- **Prompt-cache-friendly design** — the system prompt prefix is guaranteed\n  byte-identical within an epoch. Compaction requests share the same prefix structure\n  as normal calls, maximizing provider-side cache hits. Cache reads are nearly free.\n\n## Cache-Aware Compaction\n\nThe cache-aware compaction introduced in v0.16.0 is uv-agent's core optimization for\nlong-running sessions. Unlike traditional \"compress when context hits N%,\" uv-agent\nmakes an economic decision before every turn:\n\n1. The model estimates how many more conversation rounds are needed\n   (`remaining_calls_bucket`) and how strongly the task depends on history\n   (`history_dependency`).\n2. It enumerates K retention candidates and evaluates the NetGain for each: future\n   cache savings minus compaction call cost, cache invalidation loss, information\n   distortion penalty, plus context quality improvement gain.\n3. Compaction fires only when the best net gain exceeds a margin-scaled threshold;\n   otherwise it skips, avoiding wasted compression for short tasks.\n\nCompaction requests share the exact same prefix structure as normal calls (system\nprompt → tools → messages), ensuring provider-side prompt prefix caches stay warm.\nOver 90% of input tokens in a typical compaction call are billed at cached rates\n(typically 1%–10% of the normal input price).\n\nThis design draws on the DP compaction algorithm from\n[bash-agent](https://github.com/lloydzhou/bash-agent), with thanks.\n\n## Quick Start\n\nPrerequisites:\n\n- **uv** — https://docs.astral.sh/uv/getting-started/installation/\n- **ripgrep** — https://github.com/BurntSushi/ripgrep#installation\n- **Git** — needed for normal coding workflows and Worktree mode.\n\n```powershell\n# Run the latest published release\nuvx uv-agent@latest\n\n# Run from a local checkout\nuv run uv-agent\n\n# Single-turn question (no TUI)\nuvx uv-agent@latest ask \"Summarize the project structure\"\n\n# Resume an existing thread\nuvx uv-agent@latest ask --thread thr_xxx \"Continue where we left off\"\n```\n\n## Model Configuration\n\nuv-agent ships with no real provider configuration. Configure at least one provider,\nmodel, and level in `~/.uv-agent/config.json` (or project-level\n`.uv-agent/config.json`). Keep API keys in environment variables or git-ignored\nlocal config.\n\nSupported API formats:\n\n| `api` value | Format |\n| --- | --- |\n| `\"responses\"` | OpenAI Responses API |\n| `\"chat_completions\"` | OpenAI Chat Completions API |\n| `\"anthropic_messages\"` | Anthropic Messages API |\n\n\u003cdetails\u003e\n\u003csummary\u003eFull configuration example\u003c/summary\u003e\n\n```json\n{\n  \"providers\": {\n    \"deepseek\": {\n      \"base_url\": \"https://api.deepseek.com\",\n      \"api_key\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n      \"timeout_s\": 7200,\n      \"chat_completions\": {\n        \"path\": \"/chat/completions\"\n      },\n      \"message_passthrough\": {\n        \"assistant\": [\n          \"reasoning_content\"\n        ]\n      },\n      \"reasoning_display\": {\n        \"assistant_message_fields\": [\n          \"reasoning_content\"\n        ],\n        \"stream_delta_fields\": [\n          \"reasoning_content\"\n        ]\n      }\n    },\n    \"minimax\": {\n      \"base_url\": \"https://api.minimaxi.com\",\n      \"api_key\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n      \"timeout_s\": 7200,\n      \"chat_completions\": {\n        \"path\": \"/v1/chat/completions\"\n      },\n      \"anthropic_messages\": {\n        \"path\": \"/anthropic/v1/messages\"\n      }\n    }\n  },\n  \"models\": {\n    \"deepseek-v4-flash\": {\n      \"provider\": \"deepseek\",\n      \"model\": \"deepseek-v4-flash\",\n      \"api\": \"chat_completions\",\n      \"supports_images\": false,\n      \"context_window_tokens\": 1000000,\n      \"params\": {\n        \"reasoning_effort\": \"high\"\n      }\n    },\n    \"deepseek-v4-pro\": {\n      \"provider\": \"deepseek\",\n      \"model\": \"deepseek-v4-pro\",\n      \"api\": \"chat_completions\",\n      \"supports_images\": false,\n      \"context_window_tokens\": 1000000,\n      \"params\": {\n        \"reasoning_effort\": \"max\"\n      }\n    },\n    \"MiniMax-M2.7\": {\n      \"provider\": \"minimax\",\n      \"model\": \"MiniMax-M2.7-highspeed\",\n      \"api\": \"anthropic_messages\",\n      \"supports_images\": false,\n      \"context_window_tokens\": 204800\n    }\n  },\n  \"levels\": {\n    \"deepseek-flash\": {\n      \"model\": \"deepseek-v4-flash\"\n    },\n    \"deepseek-pro\": {\n      \"model\": \"deepseek-v4-pro\"\n    },\n    \"MiniMax-M2.7\": {\n      \"model\": \"MiniMax-M2.7\"\n    }\n  },\n  \"runtime\": {\n    \"default_level\": \"deepseek-flash\",\n    \"ask_default_level\": \"deepseek-flash\",\n    \"store_provider_response\": false,\n    \"max_agent_rounds\": 1000,\n    \"compression\": {\n      \"enabled\": true,\n      \"model_level\": \"deepseek-flash\",\n      \"trigger_ratio\": 0.9\n    },\n    \"title_generation\": {\n      \"enabled\": true,\n      \"model_level\": \"deepseek-flash\"\n    },\n    \"branch_name_generation\": {\n      \"enabled\": true,\n      \"model_level\": \"deepseek-flash\",\n      \"timeout_s\": 15.0\n    }\n  },\n  \"runner\": {\n    \"default_timeout_s\": 7200,\n    \"max_output_bytes\": 1000000,\n    \"scriptenv_index_url\": null\n  },\n  \"pricing\": {\n    \"currency\": \"RMB\",\n    \"unit\": \"1M_tokens\",\n    \"models\": {\n      \"deepseek-v4-flash\": {\n        \"input\": 1,\n        \"output\": 2,\n        \"cached_input\": 0.02\n      },\n      \"deepseek-v4-pro\": {\n        \"input\": 3,\n        \"output\": 6,\n        \"cached_input\": 0.025\n      }\n    }\n  },\n  \"ui\": {\n    \"completion_notification\": {\n      \"enabled\": true\n    }\n  },\n  \"plugins\": {\n    \"disabled\": [],\n    \"config\": {}\n  }\n}\n\n```\n\n\u003c/details\u003e\n\nUse `/config` in the TUI to switch default level, language, and compression\nsettings. See [configuration](docs/configuration.md) for every option and\n[config.example.json](docs/config.example.json) for a standalone example.\n\n## Everyday Workflow\n\n- Type and press `Enter` to send. Use `Ctrl+Enter` / `Ctrl+J` for newlines.\n- Type `/` from an empty composer to open the command palette; type to filter.\n  `@` for file mentions, `@@` for thread mentions.\n- `/level \u003cname\u003e` to switch models; `/status` to inspect runtime state including\n  cache compaction judge details.\n- `/goal enable [objective]` for durable task checklists across long sessions.\n- Agent View dispatches background tasks to isolated Git worktrees.\n- Use `uv-agent tui` for the legacy Textual panels (`/config`, `/models`, etc.).\n\nSee [TUI and slash commands](docs/tui.md) for the full list.\n\n## TUI Interfaces\n\n- **tui2** (default, `uv-agent` or `uv-agent tui2`) — lightweight ANSI TUI rendered\n  directly in the terminal. Compact status rows, streaming events, Goal/Worktree\n  mode, and image attachments.\n- **Textual TUI** (`uv-agent tui`) — deprecated, kept for compatibility. The older\n  Textual widget-based interface. Screenshot: [docs/t1.png](docs/t1.png).\n\n## Agent View\n\nAgent View is a dashboard for managing multiple background agent sessions. Tasks\nrun in isolated Git worktrees on auto-generated branches, keeping edits away from\nyour current checkout. Track status, skim output, continue or discard tasks — all\nfrom one panel.\n\n## Plugins\n\nPlugins are Python packages discovered via the `uv_agent.plugins` entry point. They\nrun in the uv-agent host process and can register runtime helpers, subscribe to\nevents, and submit turns from external systems.\n\n```powershell\nuvx --with your-uv-agent-plugin uv-agent@latest\n```\n\nSee [Plugin system](docs/plugins.md) for details.\n\n## Runtime \u0026 Context\n\nEvery model turn = stable system prompt + on-demand structured context.\n\n- `run_python` is the only external action surface. Scripts execute in a\n  project-shared uv environment and import `uv_agent_runtime` helpers. The uv\n  environment and working directory are separate; the cwd can change via\n  `enter_dir` or Worktree mode.\n- Runtime context (helper lists, skills, MCP servers, etc.) uses fingerprinted\n  incremental updates — only changed parts are injected, and removed capabilities\n  are explicitly marked.\n- Workspace rules are disclosed progressively: index first, full AGENTS.md only\n  when entering the relevant directory.\n- Goal mode provides a durable checklist/notes layer independent of the chat\n  transcript, preserving task progress across compaction and resume.\n- Checkpoint compaction summarizes the conversation while excluding reloadable\n  runtime context. New epochs replay structured context before retained history.\n\n## Documentation\n\n- [Configuration](docs/configuration.md)\n- [Full config example](docs/config.example.json)\n- [TUI and slash commands](docs/tui.md)\n- [Runtime and managed scripts](docs/runtime.md)\n- [Plugin system](docs/plugins.md)\n\n## Development\n\nuv-agent is self-bootstrapping — it is developed using uv-agent itself for reading,\nediting, testing, and iterating.\n\n```powershell\nuv run pytest\n```\n\nLocal debug state, screenshots, config, and run data belong in `.uv-agent/` and\nshould stay out of git.\n\n## Acknowledgments\n\nThe cache-aware compaction design draws on the DP compaction algorithm and cache\nalignment approach from [bash-agent](https://github.com/lloydzhou/bash-agent),\nwith thanks.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4fuu%2Fuv-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F4fuu%2Fuv-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4fuu%2Fuv-agent/lists"}