orion-overfit 0.4.2

Autonomous multi-agent orchestration

Orion

An autonomous coding assistant with direct access to your workspace — a Claude Code–style agent built on OpenAI function calling.

Orion runs an agentic tool-use loop: you give it a task in natural language, and it reads, writes, and edits files, runs shell commands, inspects git, and searches the web — using tools, not by handing you manual steps.

---

Features

File system

• read_file — read a file's text contents
• list_files — list a directory (relative to the workspace root)
• write_file — write content to a file, creating parent dirs as needed
• create_file — create an empty file
• delete_file — delete a file

Surgical editing

• replace_text — replace all occurrences of a string
• apply_patch — replace exactly one occurrence (fails if ambiguous)
• insert_after / insert_before — insert relative to an anchor string
• prepend / append — add text to the start or end of a file

Shell

• run_command — execute any shell command in the workspace (npm, npx, pip, pytest, builds, scaffolding…) with a configurable timeout

Git

• git_status — show working-tree status
• git_diff — show diffs (optionally staged, or scoped to a path)

Web

• search_web — search the web for titles + URLs
• read_web_page — fetch a URL and return its readable text

Agent loop

• Multi-round tool use (MAX_TOOL_ROUNDS = 20) with conversation/session state
• Automatic turn rollback on error or when the tool-call limit is reached
• Workspace-relative path enforcement to keep edits inside the project

---

Requirements

• Python >= 3.12
• An OpenAI API key
• uv (recommended) or pip

Installation

# with uv (recommended)
uv sync

# or with pip
pip install -e .

Configuration

Create a .env file in the project root:

OPENAI_API_KEY=sk-...          # required
OPENAI_MODEL=gpt-4o-mini       # optional, defaults to gpt-4o-mini
WORKER_SPACE=/path/to/project  # optional, defaults to the current directory

WORKER_SPACE is the workspace root. All file tool paths are relative to it — Orion will not use absolute or ~/ paths.

Usage

# via the installed script
orion

# or directly
python main.py

This launches the interactive REPL. Type a request in natural language, e.g.:

> create a FastAPI app in api/ with a /health endpoint and run it
> what does services/agent.py do?
> run the tests and fix any failures

---

Project layout

Orion/
├── main.py                 # CLI entrypoint (argparse → REPL)
├── config.py               # env-based config loader
├── pyproject.toml
├── api/                    # HTTP layer
├── ui/                     # banner + REPL
├── schemas/                # data schemas
└── services/
    ├── agent.py                  # AgentService + Conversation (the tool-use loop)
    ├── tools.py                  # TOOL_DEFINITIONS + ToolRegistry
    ├── file_systems_tool_service.py
    ├── edit_tool_service.py
    ├── shell_tool.py
    ├── git_tool.py
    └── browser_tool_service.py

---

Roadmap

Planned tools to reach closer parity with Claude Code:

• grep — regex content search across the tree (search_file exists but is not yet exposed in TOOL_DEFINITIONS)
• glob — recursive file matching by pattern (e.g. **/*.py)
• todo_write — task tracking for multi-step work
• Sub-agents — spawn scoped agents for parallel/independent subtasks
• Permissions layer — confirm destructive ops (write/delete/run) before executing
• git_add / git_commit — staging and committing changes
• Memory file (ORION.md/CLAUDE.md) injected into the system prompt

---

License

TBD