forge-engine 0.1.0

FORGE, a terminal AI harness engine for coding-agent workflows.

FORGE

FORGE is a small Python coding-agent harness that uses an OpenAI-compatible chat-completions API. By default it calls OpenRouter with nvidia/nemotron-3-ultra-550b-a55b:free. It gives the model a fixed set of tools for reading files, writing files, listing the sandbox, and running shell commands, then independently verifies completion instead of trusting the model's own claim.

Cloud API calls are used by default through OpenRouter.

Prerequisites

Set your OpenRouter API key before running the harness:

export OPENROUTER_API_KEY="your-openrouter-api-key"

The default API base URL is https://openrouter.ai/api/v1 and the default model is nvidia/nemotron-3-ultra-550b-a55b:free.

Installation

Install FORGE from PyPI:

pip install forge-engine

Then launch it from any terminal:

forge

Development Installation

Install FORGE in editable mode from the project root:

pip install -e .

Run the test suite with:

python3 -m pytest -q

Usage

Without arguments, forge launches interactive mode. Type a task, watch the agent work, then get the prompt back for another task.

One-shot mode is available for scripting:

forge --task "Fix the bug in calc.py" --verify pytest

The sample task can still target sandbox_project/calc.py. The verifier runs the configured command inside the active sandbox and only reports success when the check really passes.

For source-tree compatibility, the old entry point still works:

python3 run_agent.py

pip install -e . installs the required runtime dependencies, including requests and rich.

When the model writes a file, the CLI prints a unified code diff after the tool result. This lets you watch what changed in the sandbox as the agent builds, similar to a coding-agent terminal view.

Examples

Start an interactive session:

forge

Run a one-shot coding task:

forge --task "Fix the bug in calc.py" --verify pytest

Use another OpenAI-compatible API base URL:

forge --base-url http://localhost:11434/v1 --model qwen2.5-coder:7b

Interactive Commands

Command	Behavior
/cwd <path>	Change the active sandbox root to <path>.
/verify <command>	Set the verification command for the current project, such as pytest or npm test.
/model <name>	Swap the OpenRouter model for subsequent tasks without restarting.
/new-react <name>	Scaffold a Vite React app without interactive create-vite prompts, install dependencies, switch into it, and set npm run build as verification.
/clear	Reset the session transcript while keeping project/model/verify settings.
/help	List all commands.
/exit or /quit	Exit cleanly.

The CLI persists sandbox_root, verify_command, and model in .qwenagent-session.json in the active project directory.

Verification Fallback

If no verification command is set when the agent calls task_complete, the harness first tries to auto-detect one: pytest, npm test, or make test.

If nothing is detected, the CLI asks you what command to run. Pressing Enter explicitly accepts the agent's claim without automated verification. That is a visible human decision, not an automatic trust fallback.

Architecture

Concept	This project
Agentic loop	harness/orchestrator.py
Tool use	harness/tools.py
Sandboxing / permissions	harness/sandbox.py
Context management	harness/transcript.py
Knowing when a task is done	harness/verifier.py
The model (swappable)	harness/llm_client.py

Model Behavior

Models vary in how reliably they produce tool calls. Expect occasional malformed tool-call JSON, premature task_complete calls that bounce off the verifier, and loop-guard triggers on harder tasks.

Those outcomes are expected guardrail behavior, not harness bugs. The model's task_complete call is only a request for independent verification.

Next Steps

• Add real sandbox isolation with Docker instead of only path confinement.
• Replace exact-repeat loop detection with richer "no progress" detection.
• Try another OpenRouter model by changing the model value with /model <name> or forge --model <name>.

Contributing

Contributions are welcome. For local development, install the package in editable mode, run the tests, and keep changes focused on one behavior at a time:

pip install -e .[test]
python3 -m pytest -q

License

FORGE is licensed under the MIT License. See LICENSE for details.