Skip to content

getting-started.md

Latest commit

 

History

History
111 lines (76 loc) · 2.36 KB

getting-started.md

File metadata and controls

111 lines (76 loc) · 2.36 KB

Getting Started

AgentForge is a Python CLI package for learning how coding-agent harnesses work. It runs in your terminal, loads configuration from your project and user environment, calls an LLM provider, and exposes local tools through an approval-aware harness.

Install

From PyPI after release:

pip install agentforge-harness

From a local checkout:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

First Run

Create config with the setup wizard:

agentforge init

Check local readiness:

agentforge doctor

Start the TUI:

agentforge

Or run a single prompt:

agentforge run "read this project and summarize the harness architecture"

Minimum Provider Setup

AgentForge needs one configured model provider. The setup wizard writes the project config and tells you which API key to set.

For hosted providers such as OpenRouter, OpenAI, and Anthropic, the wizard asks for the provider, API key, and default model. It does not ask for a base URL. OpenRouter gets its default base URL automatically, while OpenAI and Anthropic use their SDK defaults.

For custom OpenAI-compatible providers, the wizard asks for the base URL first, then the API key and model.

Common keys:

OPENROUTER_API_KEY=...
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
API_KEY=...

See Provider Setup for provider-specific examples.

Basic TUI Flow

Inside the interactive session:

/help
/doctor
/tools
/skills
/plan
/build
/stats
/exit

Recommended first manual test:

  1. Ask AgentForge to list files.
  2. Ask it to read README.MD.
  3. Ask it to create a tiny file and approve the write.
  4. Ask it to edit that file.
  5. Run /checkpoint.
  6. Run /export html.
  7. Run /stats.

Where State Is Stored

Project config lives in:

.agentforge/config.toml

Runtime state such as sessions and checkpoints is stored in the platform data directory for agentforge. Use /sessions, /resume, /checkpoints, and /restore to inspect and reuse it.

Development Checks

For local development:

HOME=/tmp/agentforge-test-home python3 -m pytest -q
python3 -m compileall -q agentforge_harness tests main.py scripts
python3 scripts/release_smoke.py

Use an isolated HOME during tests so session/config writes do not depend on machine-specific user directories.