Open source · MIT licensed · Alpha

One agent.
Your terminal.
Real work.

Give one a goal. It plans, uses tools, executes work, verifies results, and reports back — entirely in your terminal.

Get started View on GitHub
Install: pip install one-agent
Run: one run "fix the failing tests and summarize the changes"
one — autonomous agent
$ one run "fix the failing tests and summarize the changes"

→ inspecting repository
→ reading failing tests
→ planning changes
→ editing src/auth.py
→ editing src/middleware.py
→ running pytest
✓ verification complete
✓ goal completed

Fixed auth session handling and middleware error propagation.
result verified. Changes summarized.

Why ONE?

I believe the future of AI is local-first.

  • Local-first. Most everyday AI tasks should run on your own hardware.
  • You decide. Local, cloud, or hybrid — the choice is yours.
  • The future is local. Local models will power the future of everyday work.

Your hardware. Your models. Your rules. Not theirs.

How it works

Give it the outcome.
one handles the loop.

The agent takes your goal, breaks it into a plan, uses tools to execute, verifies the result, and reports back. Repeat until done.

G

Goal

You describe the desired outcome in plain terms.

P

Plan

For complex tasks, the agent generates a step-by-step plan.

T

Tools

Reads files, edits code, runs shell commands, searches the web.

E

Execute

Applies changes and runs validation — iteratively.

V

Verify

Tests pass, diffs reviewed, result confirmed.

R

Report

Final summary returned to you — or to CI.

Autonomous execution

Run tasks without a live terminal.

one run executes headless tasks end-to-end. Give it a goal, get back a summary — or structured JSON output for integration with CI pipelines and scripts.

# Autonomous headless task
one run "fix the failing tests"
# Structured JSON output
one run "refactor auth module" --json
{"summary": "Fixed auth session",
  "goalSuccess": true,
  "finished": true}
Interactive terminal UI

A rich TUI built on Textual.

Stream responses in real-time, inspect tool lifecycle as it happens, steer the agent mid-task, continue sessions, and control everything with keyboard shortcuts. Slash commands for /help, /steer, /follow, /abort, and more.

one v0.1.x — session: parser fix
✓ tool: read(
    parser/tokenize.py
thought: Checking the regression…
✓ tool: edit(
    parser/tokenize.py:23
thought: Applying fix and retesting.
✓ tool: bash(python -m pytest -q)
    focused verification passed
→ /details-show [Ctrl+D]
Stay in control

Autonomy without surrendering control.

Enable cooperation mode to require human approval before any mutating tool executes — bash, write, edit, plan, or apply_patch. In the TUI toggle it with Ctrl+Z, or steer, follow-up, and abort at any time. Autonomous does not mean uncontrolled.

# Headless with cooperation gate
one run "refactor auth" --cooperation
# Write answers to a file for polling
one run "fix tests" --answer-file /tmp/answer.txt --steer-file /tmp/steer.txt
Bring your own model

OpenAI, Anthropic, Gemini, Ollama, llama.cpp, and more.

Connect to any OpenAI-compatible API, or run fully local with Ollama and llama.cpp. Credentials are resolved from runtime input, stored auth, or environment variables. No vendor lock-in.

# Hosted providers
one --provider openai --model gpt-4o-mini
one --provider anthropic --model claude-sonnet-4-20250514
one --provider gemini
# Local models
one --provider ollama --model llama3.2
one --provider llama.cpp --model local
Extend it

MCP servers, extensions, and skills.

Add capabilities via MCP servers (stdio or streamable HTTP), custom extensions with hooks and commands, or skills — metadata-driven prompt profiles loaded on demand. Everything is discovered from configurable paths.

/mcp list
web-search [active] (stdio)
filesystem [active] (streamable-http)
/skill:code-review
Loaded skill: code-review
Profile: strict, 3-pass review
Built for automation

Not just a terminal tool — a programmable agent.

RPC mode for long-lived orchestrator integration, JSON output for machine consumption, task files with parameter substitution, and answer/steer files for human-in-the-loop workflows outside an interactive shell.

# RPC — long-lived integration
echo '{"id":"p1","type":"prompt","message":"test suite"}'
| one --mode rpc
# Task file with parameters
one run @task.txt --param component=auth
Modes & interfaces

Five ways to use one.

Choose the right interface for the job — from interactive work to machine orchestration.

TUI
Human-driven interactive work with streamed responses, slash commands, and session management.
one --mode tui
Text
One-shot output. Send a message, get the final assistant text.
one --mode text
JSON
Machine-readable session messages. Structured output for scripts and integrations.
one --mode json
RPC
Long-lived JSON-lines protocol. Full control channel access for orchestrators.
one --mode rpc
one run
Autonomous headless tasks and CI workflows. Goal → plan → execute → report.
one run <task>
In action

Watch one work.

bash — one
$ one run "find the bug causing the failing parser tests and fix it"
one
├​​​​– Inspecting repository
├​​​​– Running targeted tests
├​​​​– Found regression in parser/tokenize.py
├​​​​– Applying patch
├​​​​– Running tests
├​​​​└​​​​​​​​​​– verification passed
└​​​​​​​​​​– Verifying diff
✓ Goal completed
Fixed parser handling for escaped delimiters.
84 tests passed.
Trust & safety

Autonomy with a human in the loop.

Cooperation mode is an approval gate — not a sandbox. You stay in control.

♦ Approval gates

Require human approval before bash, write, edit, plan, and apply_patch tools execute. Toggle with Ctrl+Z in the TUI or use --cooperation in headless mode.

↗ Steering & follow-ups

Guide the agent mid-task with /steer or /follow. Submit follow-up instructions without restarting the session.

▓ Abort controls

Abort any turn with Ctrl+C, reject pending approvals, or use RPC abort channels for programmatic control.

◉ Full visibility

Every tool call, MCP request, and plan step is visible in real-time. Inspect tool results with /details-show. No hidden actions.

⚠ Workspace trust: Extensions and MCP servers are not sandboxed — they run with your permissions. Start one --no-extensions --no-mcp in untrusted repositories. Cooperation mode is an approval gate, not a security boundary.
Ecosystem

Bring your own models.
Connect your own tools.

one
OpenAI / OpenAI-compatible
Anthropic
Gemini
ChatGPT / Codex
Ollama
llama.cpp
MCP servers
Skills & Extensions
Install

Get started in seconds.

Available from PyPI or build from source. Requires Python 3.12+.

From PyPI
pip install one-agent
one --help
From source
git clone https://github.com/noxgle/one.git
cd one
pip install -e '.[dev]'
one --help
Open source

Built in the open.
Built for developers.

MIT licensed. Written in Python. GitHub-native development. Community contributions welcome.

♦

MIT License

Free to use, modify, and distribute.

◆

Python 3.12+

Clean, typed, well-tested code.

⌘

GitHub-native

Issues, PRs, CI, and CHANGELOG all on GitHub.

◂

Community-driven

Contributions, extensions, and skills welcome.

⚡ Currently in Alpha (0.1.x) — APIs and tool contracts may evolve

Your next task starts with one command.

Give your terminal a goal. It'll handle the rest.

pip install one-agent
Get started GitHub