Get started with Adaptea

Adaptea is an orchestrator for local coding agents. It connects to your local inference engines—LM Studio, Ollama, llama.cpp, or vLLM—through OpenCode, then plans, schedules, validates, and integrates the work. Both the native desktop app and the keyboard-first terminal CLI share the same Python core and durable .adaptea state.

Local by design

Your repository, code changes, prompts, model weights, and run telemetry stay entirely on your machine. Adaptea never depends on cloud APIs.

Choose the right desktop build

Processor architecture matters even when the operating system name is the same. The current public beta publishes these desktop installers:

AVAILABLEMac · Apple siliconM1, M2, M3, M4, or newer · ARM64 · macOS 12+

AVAILABLEMac · Intelx86_64 Mac models · macOS 12+

SOONWindows · Intel or AMD64-bit x64 desktop installer in development; coming soon.

SOONWindows · ARM64ARM64 Snapdragon desktop installer in development; coming soon.

On a Mac, open Apple menu → About This Mac. “Chip” followed by Apple M means Apple silicon; “Processor” followed by Intel means Intel. Windows desktop builds will be available soon.

Requirements

Before executing coding runs with Adaptea (desktop or CLI), ensure the following prerequisites are available on your machine:

Git for isolated task worktrees and automated branch merging
Local Inference Engine: LM Studio, Ollama, llama.cpp (llama-server), or vLLM running locally with at least one model
OpenCode as the coding worker runtime
32K context minimum; 65,536 tokens is strongly recommended for planning

Adaptea's Environment view and adaptea doctor CLI command diagnose these layers in dependency order and provide concrete remedies when anything is missing.

Your first run

1
Open a project folder
Adaptea reads no repository until you explicitly open it or run inside it.
2
Finish Environment setup
Select the inference backend, choose models, and run calibration if you use LM Studio adaptive scheduling.
3
Start a piece of work
Describe the goal in plain language, then review and edit the generated dependency plan.
4
Choose a run mode
Adaptive is the normal choice for LM Studio. Serial, Fixed, and Naive modes are also available for control and comparison.
5
Review the result
Passing tasks merge into an integration branch and can be applied to your project as one squash commit.

Terminal installation & upgrades

The terminal edition of Adaptea provides a full keyboard-first experience. It runs the exact same Python application services, uses identical scheduling algorithms, and reads/writes the same durable .adaptea workspace state as the desktop app.

Quick one-line installer (macOS & Linux)

On macOS or Linux, install Git and run the automated bootstrap installer:

macOS or Linux terminal · latest

curl -LsSf https://adaptea.dev/install.sh | sh

The bootstrap script installs an isolated Python 3.12 runtime and the latest tagged release. You do not need to install or manage Python or uv manually. To upgrade Adaptea to the newest release, simply re-run the same command.

Source install with uv (All platforms)

For developers or platforms without a prebuilt package (including Intel Macs, Linux workstations, and Windows PowerShell):

Source checkout & uv setup

git clone https://github.com/tahaenesaslanturk/Adaptea-Core.git
cd Adaptea-Core
uv sync
uv run adaptea --version

Interactive REPL & TUI dashboard

Adaptea features two complementary terminal interfaces depending on whether you prefer a quick command line prompt or a rich live monitoring dashboard:

adapteaInteractive REPL

Launches the fast interactive command center. Open projects, run setup, review diagnostics, calibrate models, generate plans, and execute tasks without leaving the prompt.

adaptea --dashboardFull-screen TUI

Launches the full-screen widget dashboard (alias: adaptea tui) built with Textual. Displays real-time worker slots, telemetry graphs, queue status, and task logs.

Terminal interface commands

# Interactive command REPL
adaptea

# Full-screen live monitoring TUI
adaptea --dashboard

Setup, doctor diagnostics & smoke test

Before launching a large coding task, Adaptea includes diagnostic tools to ensure your local inference server, models, Git setup, and OpenCode workers are configured properly.

Interactive Setup Center (`adaptea setup`)

The interactive setup center inspects your machine and walks through necessary repairs one step at a time: discovering LM Studio, Ollama, llama.cpp, or vLLM, checking the local server status, inspecting model context limits, and configuring OpenCode project-locally.

Interactive setup center

# Interactive step-by-step setup
adaptea setup

# Apply safe fixes automatically while confirming installs
adaptea setup --auto

# Show real-time command outputs and detailed logs
adaptea setup --verbose

Diagnostic Health Check (`adaptea doctor`)

Runs a non-destructive audit of host tools, backend endpoints, loaded model context size (clamped to 32,768+ tokens), project configuration, and capacity state:

Run diagnostics

adaptea doctor

Deterministic MVP Smoke Test (`adaptea smoke-test`)

Verifies the complete scheduler/worktree/worker/validation/merge pipeline in a temporary, deterministic Git fixture. It tests model responses and code merges without making any changes to your project repository:

Smoke test

# Execute end-to-end verification
adaptea smoke-test

# Preserve the temporary fixture for manual inspection
adaptea smoke-test --keep-fixture

Planning, running & resuming work

Adaptea decomposes high-level development goals into a validated task graph, executes ready tasks in parallel Git worktrees, validates changes with your test command, and merges passing work into a clean squash commit.

1. Generate a dependency plan (`adaptea plan`)

Requests a validated task breakdown from OpenCode and saves the plan specification under .adaptea/runs/plan-<timestamp>-<id>/plan.json:

Plan a development goal

adaptea plan "Build authentication with login, registration, password reset and tests"

2. Execute a run (`adaptea run`)

You can execute directly from a natural language goal, or pass an edited plan.json file. Choose the admission scheduler that fits your machine:

Scheduler	CLI Flag	Behavior & Recommended Use
Adaptive	`--scheduler adaptive`	(Default for LM Studio) Watches live queue depth and generation pressure. Raises admission when headroom exists and delays workers when busy.
Fixed	`--scheduler fixed --concurrency <N>`	Maintains a constant concurrent worker limit (e.g. `--concurrency 4`). Useful for controlled benchmarking.
Naive	`--scheduler naive --max-agents <N>`	Admits all ready tasks simultaneously up to the specified ceiling without checking server load.

Execute runs

# Adaptive run from natural language goal
adaptea run "Build user dashboard with dark mode toggle and unit tests"

# Run from a previously validated plan file
adaptea run --plan .adaptea/runs/plan-2026-08-31-a1b2c3d4/plan.json

# Fixed concurrency execution
adaptea run "Implement search filters" --scheduler fixed --concurrency 4

# Naive parallel execution
adaptea run "Refactor logging helpers" --scheduler naive --max-agents 8

3. Inspect status & resume runs (`status` & `resume`)

Run state is durable. If your machine shuts down or a process is stopped, you can inspect status and resume without losing completed work:

Status and resume commands

# Show status of the latest run
adaptea status

# Show status of a specific run
adaptea status <run-id>

# Safely resume an interrupted run without re-running merged tasks
adaptea resume <run-id>

Managing the Adaptive Model Fleet via CLI

When running multiple local models or model instances, Adaptea’s Model Fleet assigns explicit roles (planner, reviewer, worker) and routes tasks to capability tiers (strong vs fast pool).

adaptea fleet listDiscovery

Lists discovered downloaded models, loaded instance identifiers, slots, assigned roles, and capability tiers.

adaptea fleet statusPool status

Displays active worker pools, target slots, and checks whether the fleet profile (.adaptea/fleet.json) is calibrated or stale.

adaptea fleet configureRole config

Interactive or scriptable tier assignment for planner, reviewer, strong worker, and fast worker pools.

adaptea fleet calibrateTopology sweep

Measures multi-instance continuous batching vs replica candidates and validates the best topology via deterministic agent tests.

Model fleet management commands

# List downloaded models & loaded instances
adaptea fleet list

# Inspect fleet pools and profile freshness
adaptea fleet status

# Configure model tiers and roles
adaptea fleet configure

# Measure candidate fleet topologies and write .adaptea/fleet.json
adaptea fleet calibrate --repetitions 3

Concurrency calibration & benchmarks

Adaptea bases its admission targets on real measurements on your hardware rather than generic estimates.

Single-model calibration (`adaptea calibrate`)

Sweeps configured concurrency levels (e.g. 1, 2, 4, 8), measuring time-to-first-token (TTFT), token throughput, and memory bandwidth scaling. Results are written to .adaptea/capacity.json, CSV, and standalone HTML reports:

Run concurrency calibration

# Standard calibration across concurrency levels
adaptea calibrate --concurrency 1,2,4,8 --repetitions 3

# Fast development check
adaptea calibrate --quick

Reproducible multi-mode benchmark (`adaptea benchmark`)

Fairly evaluates Serial, Fixed, Naive, and Adaptive execution modes on the exact same clean Git commit and static plan. Repetitions are executed in an interleaved, seeded order:

Benchmark execution & report

# Fair comparison of Serial, Fixed, Naive, and Adaptive
adaptea benchmark --plan fixtures/benchmark/plan.json --repetitions 3 --fixed-concurrency 2 --max-agents 8

# Generate aggregate JSON, CSV, and HTML report
adaptea report

Worker command security policy

Coding workers operate under a project-local, non-interactive command security policy. Commands are divided into three clear categories:

Category	Effective Action	Examples & Requirements
Safe default	Allow automatically	Read-only operations and testing commands (e.g. `pytest`, `npm test`, `cargo test`, `git status`).
Approval required	Deny unless approved	Package installation (`npm install`, `pip install`), network access, Git mutations. Require approval in `adaptea.toml`.
Blocked	Always deny	Host-wide privilege escalation (`sudo`), disk formatting, destructive deletions (`rm -rf /`), force pushing. Cannot be overridden.

To inspect your project's active command security policy in the terminal:

Inspect command policy

adaptea command-policy

To approve specific command patterns, add them under [worker.command_security] in your project's adaptea.toml:

adaptea.toml configuration

[worker.command_security]
approved_commands = [
  "npm install zod@4",
  "pip install pytest-asyncio"
]

Adaptive scheduling

Adaptea controls how many coding workers are allowed to start. With LM Studio, it watches live inference pressure and adjusts an admission target using a moving window, hysteresis, and cooldown. A lower target never terminates healthy work already in progress.

adaptea / controller

fan_out(t) = min(admission_target(t), ready_tasks(t),
                 user_ceiling, backend_parallel_limit)

For llama.cpp, Adaptea natively monitors active processing slots (/slots). For vLLM, it parses live KV-cache pressure and engine queue metrics (/metrics). For Ollama, it maintains a safe concurrency ceiling instead of synthesizing unavailable telemetry.

Adaptive Model Fleet

Fleet mode is optional. You can assign explicit roles such as planner, worker, and reviewer to one or more local model instances. User-defined tiers let Adaptea route low-complexity tasks to a fast pool and keep high-complexity work on the strong tier.

No benchmark theater

Adaptea does not assume that more instances are faster. It measures candidate topologies on your hardware and refuses automatic choices when required facts are missing.

Worktrees and validation

Every coding task runs in an isolated Git worktree. Adaptea detects the project’s validator—such as pytest or a real npm test script—or uses the explicit command in adaptea.toml. Only passing task branches are merged.

Run state is durable under .adaptea/. If the app or machine stops, Resume reconstructs the run without blindly renewing exhausted retry budgets.

Verify your download

Every release includes platform-specific SHA-256 checksums. The macOS builds (Apple silicon and Intel) are Developer ID signed, notarized by Apple, and tickets are stapled directly to the disk image.

Match the release version

The installer filename, checksum file, and version shown on the Download page must agree. Do not install an artifact whose checksum does not match.

macOS checksum

shasum -a 256 -c Adaptea-macos-arm64.dmg.sha256

On macOS, you can additionally run spctl --assess --type execute --verbose /Applications/Adaptea.app after installation to verify Apple notarization.

NEXTDownload the public beta→