opencodr 0.1.8

open source terminal-based coding agent

Open source coding agent in your terminal
· Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
   • Initialization
   • Configuration
3. Usage
   • Generate
   • Workspace
4. Contributing

About The Project

opencodr is a simple recursive function combined with the Function Calling API + Model Context Protocol to create agentic behavior.

• ❌ No Auth Screens
• ❌ No Provider Lock-in

API Key(s) + A Terminal Is All You Need™️

Built With

Getting Started

Prerequisites

• Python>=3.13
• Docker (Optional but highly recommended)

Installation

> MacBookPro:example user$ pip install opencodr

> MacBookPro:example user$ opencodr init opencodr --help

✋ opencodr project not initialized. Run `opencodr init`

Initialization

Run the following command from the root of your project:

> MacBookPro:example user$ opencodr init

📄 .rc file generated at /workspace/example/.opencodr/.rc
✔️ .opencodr added to .gitignore

> MacBookPro:example user$ opencodr --help

 Usage: opencodr [OPTIONS] COMMAND [ARGS]...

╭─ Options ────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the     │
│                               current shell.                 │
│ --show-completion             Show completion for the        │
│                               current shell, to copy it or   │
│                               customize the installation.    │
│ --help                        Show this message and exit.    │
╰──────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────╮
│ gen                                                          │
│ workspace                                                    │
╰──────────────────────────────────────────────────────────────╯

Configuration

/workspace/example/.opencodr/.rc

# List of allowed directories, Separated with colons (:) e.g "/path/to/a/dir:/path/to/b/dir"
export OC_PATH="$(pwd)"

# <provider>/<model_name>
export OC_MODEL="openrouter/openai/gpt-4o"

# export OC_BASE_URL=""
# export OC_MAX_TOKENS=""
# export OC_MAX_DEPTH=""

# Provider API Keys
export OPENROUTER_API_KEY=""
# export OPENAI_API_KEY=""
# export ANTHROPIC_API_KEY=""

NOTE: See https://docs.litellm.ai/docs/providers for the list of supported models

/workspace/example/.opencodr/mcp.json (Optional)

{
  "sqlite": {
    "command": "uvx",
    "args": ["mcp-server-sqlite", "--db-path", "./test.db"]
  },
  "puppeteer": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
  }
}

Prompt Overrides (Optional)

/workspace/example/.opencodr/SYSTEM.txt

/workspace/example/.opencodr/REPROMPT.txt

(back to top)

Usage

generate

> MacBookPro:example user$ opencodr gen --help

 Usage: opencodr gen [OPTIONS]

╭─ Options ────────────────────────────────────────────────────╮
│ --f           TEXT  Load prompt from file [default: None]    │
│ --help              Show this message and exit.              │
╰──────────────────────────────────────────────────────────────╯

workspace

NOTE: Requires Docker

> MacBookPro:example user$ opencodr workspace --help

 Usage: opencodr workspace [OPTIONS] COMMAND [ARGS]...

╭─ Options ────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────╮
│ create   Creates a docker image to sandbox the agent         │
│ start    Shortcut to start the container                     │
│ stop     Shortcut to stop the container                      │
╰──────────────────────────────────────────────────────────────╯

Contributing

Prerequisites

• uv

Repo Setup

git clone https://github.com/notpolomarco/opencodr.git
cd opencodr

Create Virtual Environment

uv venv
source .venv/bin/activate

Install

uv pip install -e ".[dev]"
pre-commit install
pre-commit install --hook-type pre-push

NOTE: to test any new features in workspace mode, build the base image from /opencodr/dockerfile.dev

uv build
docker build -t opencodr/base -f dockerfile.dev .