Starforge

Starforge is a general-purpose autonomous agent runtime.

It is designed to run domain-agnostic objectives through tools, not through hardcoded assumptions about coding, tests, or any single workflow.

What It Can Do

• debug code as one optional use case
• run arbitrary tasks through CLI tools or APIs
• perform research workflows such as crypto analysis
• plug into automation systems as a reusable runtime component

Core Design

• Task-agnostic engine: run(objective="analyze BTC trend and summarize key signals")
• Simple adaptive loop: act -> observe -> adapt -> repeat
• Optional model-feedback replanning in autonomous mode: when the tool queue is empty, Starforge can ask a model for the next tool call and continue iterating
• Completion quality gate for model-orchestrated runs: done-token completions are scored and may be refined before stop
• Tool-based execution: the runtime acts through tools such as run_command, read_file, write_file, http_request, web_search, and read_webpage
• Structured observations: every tool returns a normalized observation payload
• Portable memory: reusable patterns live in ~/.starforge/, not inside project repos
• Adapters configure environments without embedding business logic into the core engine

Folder Structure

starforge/
  __init__.py        # public API: run(), create_runtime()
  __main__.py        # python -m starforge
  cli.py             # CLI entrypoint
  actions.py         # action requests and action records
  adapters.py        # CLI / code / API adapter configuration
  context.py         # runtime context normalization
  engine.py          # generic execution loop
  memory.py          # portable similarity-based memory store
  observations.py    # normalized observation model
  tools/
    base.py          # tool protocol + registry
    builtin.py       # built-in tools
examples/
  code_debugging.py
  crypto_research.py
main.py              # thin CLI proxy for local repo usage

Library Usage

from starforge import run

result = run(
    objective="analyze BTC trend and summarize key signals",
    context={
        "working_dir": ".",
        "constraints": [],
        "api_requests": [
            {
                "url": "https://api.coingecko.com/api/v3/coins/bitcoin/market_chart",
                "params": {"vs_currency": "usd", "days": "7", "interval": "daily"},
            }
        ],
    },
    config={
        "adapter": "api",
        "max_steps": 8,
        "mode": "autonomous",
    },
)

Return shape:

{
    "success": bool,
    "steps": int,
    "actions": [...],
    "result": any,
    "confidence": float,
}

Pluggable runtime usage:

from starforge import create_runtime

runtime = create_runtime(adapter="cli", memory_root="/tmp/starforge-memory")
result = runtime.run(
    objective="inspect the workspace and run the smoke command",
    context={
        "working_dir": ".",
        "commands": ["python -m pytest -q"],
    },
    config={"max_steps": 3},
)

CLI Usage

starforge run "analyze ETH price trend last 7 days" --adapter api

starforge run "inspect objective and continue autonomously" --human --model-feedback --max-model-replans 3

Model feedback can use:

• Ollama (--model-provider ollama --model-name qwen2.5:7b)
• OpenRouter (OPENROUTER_API_KEY=... + --model-provider openrouter)
• Google / Nvidia providers via their API keys.

Model-Orchestrated Completion Gate

When model-orchestrated mode is enabled with a required completion token (default: DONE_STOP_AUTONOMOUS), completion is validated with a quality review before stopping:

• The model should return structured completion JSON with self_review.score in [0, 1] and a short result summary.
• Default completion threshold is 0.97 (completion_score_threshold).
• If score is below threshold, Starforge requests one refine cycle by default (completion_max_refines=1).
• After the refine budget is used, the model may still stop by setting cannot_improve=true in self_review.

Example completion payload:

{
  "done": true,
  "final_answer": "All required checks passed. DONE_STOP_AUTONOMOUS",
  "self_review": {
    "score": 0.98,
    "result": "Objective satisfied with test and file evidence."
  }
}

Useful config keys:

• require_done_stop_token (bool): enforce explicit done token on completion.
• done_stop_token (str): completion token text (default DONE_STOP_AUTONOMOUS).
• completion_score_threshold (float): minimum acceptable self-review score.
• completion_max_refines (int): refine attempts before cannot_improve can be accepted.

starforge run --objective "fix build errors" --adapter code --working-dir ./demo_project --command "pytest -q"

You can also run the repo-local entrypoint:

python main.py run "analyze BTC trend and summarize key signals"

Adapters

Built-in adapters keep the engine generic while configuring tool sets for different environments.

• cli: run_command, read_file, write_file, list_files, web_search, read_webpage
• code: same tool set, plus command defaults derived from diagnostic_command, test_command, and build_command
• api: http_request, web_search, read_webpage, write_file, read_file

Observation Format

All tool outputs are normalized like this:

{
    "type": "command_result" | "file_read" | "api_response" | "search_results" | "webpage_read",
    "content": ...,
    "metadata": {...},
}

web_search is available as an optional tool. The runtime can use it when it helps, but it is not mandatory for every objective.

Memory

Starforge stores portable memory in ~/.starforge/patterns.jsonl.

Each entry captures a reusable behavior pattern instead of a task-specific hack:

{
    "pattern_type": "repeated_failure",
    "context": "run_command:{...}",
    "resolution_strategy": "Avoid repeating the same failing action without changing inputs or switching tools.",
    "confidence": 0.6,
    "metadata": {...},
}

Retrieval is similarity-based, optional, and domain-agnostic.

Example Workflows

Code debugging:

python examples/code_debugging.py

Crypto research:

python examples/crypto_research.py

Installation

pip install -e .

This exposes the starforge CLI and the starforge Python package.