Flex

An agent-loop engine in Rust — one interface over LLM APIs and external coding agents, with one event stream out.

Point it at Anthropic, OpenAI, Gemini, DeepSeek, Bedrock, Ollama or Copilot — or
at Claude Code, Cursor Agent, opencode, Grok Build and any ACP agent — and every
one of them looks the same to your code: the same Agent interface going in, the
same typed event stream coming out. Run it headless from CI, embed it in a Rust
binary, or supervise it in the desktop shell.

Pre-alpha. APIs, wire formats, and the project name itself are still
moving. See Status before you build on it.

Try it

./scripts/install_mac.sh          # macOS → ~/.local/bin/flex + /Applications/Flex.app
flex doctor                       # shows the resolved provider, model and workdir

cd my-project
flex run -p "summarize the README"

Windows: .\scripts\install_windows.ps1 (PowerShell) or
./scripts/install_windows.sh (Git Bash / MSYS2; WSL installs the CLI only).

No local project needed — headless runs get read-only tools:

flex run -p "what happened in fusion energy in 2024-2025?"

Pick a provider and model explicitly, and pass a key inline to bypass the
environment:

flex run --provider deepseek --model deepseek-v4-pro -p "explain this codebase"
flex run --provider anthropic --model claude-sonnet-4 -p "..." --workdir ~/my-project
flex run --provider deepseek -p "..." --key sk-...

What it is

• One Agent interface, many implementations. The native loop calls LLM
  APIs directly (Anthropic, OpenAI, Gemini, Ollama, Bedrock, Copilot, DeepSeek).
  Delegators drive external coding agents — Claude Code, Copilot CLI, opencode,
  Cursor Agent, Grok Build, and ACP agents such as Gemini CLI and Goose — behind
  the same interface. Any of them can run as a subagent of any other.
• One stream format. Every provider and every external agent is normalized
  into a single typed, markdown-flavored event stream: text, thinking, tool
  calls, tool results. Consumers render one format, always.
• First-class ToolCalls. Every invocation is a tracked record — request,
  response, status machine, timing, permission trail.
• Headless by contract. A versioned wire protocol (NDJSON over stdio, ACP
  for editors) lets UIs, CLIs and CI drive the engine, the same way claude -p
  does.
• Observable by default. Structured logs and metrics for every step, derived
  from the same canonical event stream that is persisted as the session's
  append-only log.
• Plugins. Base tools ship in the box (Read, Write, Edit, Glob, Grep, Bash,
  WebFetch). The optional search plugin adds search_web, scrape_page and a
  researcher role, chaining DuckDuckGo and SearXNG with automatic fallback;
  scrape_page strips navigation and boilerplate down to the content core, with
  optional link extraction for recursive exploration.

The engine is not a UI or a CLI product itself — it is what powers them.

Desktop app

packages/desktop is a native app (Tauri 2 + React) and a second composition
root over AgentBuilder, alongside the flex CLI. It is an agents-first
supervision UI, not an IDE:

• Multi-provider sessions with named connection profiles (default + fallback
  models), AWS Bedrock bearer auth, and a cross-provider tier orchestration mode.
• Per-session git-worktree isolation with a review flow — per-file/hunk
  keep/undo, checkpoints, and a commit center (commit / push / branch / PR).
• A chat feed that clusters tool calls, streams thinking, and folds finished
  turns into a summary with duration, tokens and cost.
• Closable tabs for an embedded browser, real PTY terminals, a read-only agent
  terminal, per-file diffs, and a Monaco files pane (open/edit — no LSP,
  debugger or extension marketplace).
• Plan mode with approval, a live subagent viewer, per-project and global memory,
  MCP servers, a per-model effort picker, background bash, and
  retry-on-network-loss.

Native LLM providers only in-app; external-agent connectors are a CLI/headless
concern today.

./scripts/install_mac.sh     # install CLI + desktop

cd packages/desktop          # or run in dev
pnpm install
pnpm tauri dev

Prerequisites, provider setup and keyboard shortcuts:
packages/desktop/README.md.

Embed it

[dependencies]
agentloop-sdk = { git = "https://github.com/ndolinschi/Flex", features = ["search"] }

use agentloop_sdk::{AgentBuilder, OutputVerbosity};

// Auto-detect the provider from the environment.
let service = AgentBuilder::new().build()?;

// Or choose provider, model, plugins, verbosity and headless mode.
let service = AgentBuilder::new()
    .provider("deepseek")
    .model("deepseek-v4-pro")
    .provider_key("deepseek", "sk-...")
    .enable_plugin("search")
    .verbosity(OutputVerbosity::Low)
    .headless()
    .build()?;

Status

Pre-alpha: APIs, wire formats and the name are all still moving.

Flex is not a Cursor or VS Code replacement. It is an agent-loop harness and
control plane — compose providers and external agents, run them headlessly or
supervise them in a thin shell. Keep your editor; Flex is the runtime around the
model, not a coding IDE.

Before installing, confirm you want a harness rather than an IDE, have
Rust / Node / pnpm for the desktop build, and hold at least one usable provider
key or external agent CLI. Then run flex doctor.

Repository layout

Architecture map, layer contracts and contributor rules live in
AGENTS.md — start at CONTRIBUTING.md for the
short version. Vulnerabilities: SECURITY.md.

├── AGENTS.md                  # architecture map, layer contracts, contributor rules
├── CONTRIBUTING.md            # where to start; defers to AGENTS.md
├── SECURITY.md                # private vulnerability reporting
├── scripts/
│   ├── install_mac.sh         # build + install CLI + Flex.app (macOS)
│   ├── install_windows.ps1    # same for Windows (PowerShell)
│   └── install_windows.sh     # Windows via Git Bash / MSYS2 (WSL: CLI only)
├── packages/
│   ├── desktop/               # Tauri 2 + React desktop app — second composition root
│   ├── engine/                # cargo workspace — provider-agnostic native engine
│   │   ├── crates/
│   │   │   ├── contracts/     # pure data: events, content blocks, ToolCall, branding
│   │   │   ├── core/          # traits: Agent, Provider, Tool, SessionStore, Plugin, Workspaces
│   │   │   ├── loop/          # NativeAgent — turn iteration, tool dispatch, model failover
│   │   │   ├── engine/        # EngineService front door — provider-agnostic composition
│   │   │   ├── prompts/       # system-prompt assembly + slash-command registry
│   │   │   ├── session/       # SessionStore impls (memory, JSONL)
│   │   │   ├── tools/         # base tool set: Read/Write/Edit/Glob/Grep/Bash/WebFetch
│   │   │   ├── hooks/         # pre/post-turn hooks, formatters, diagnostics
│   │   │   ├── workspace/     # Workspaces impl: git-worktree session isolation
│   │   │   ├── mcp/           # MCP client (rmcp) → Tool bridge
│   │   │   ├── transports/    # stdio/NDJSON transport, ACP adapter
│   │   │   └── testkit/       # MockProvider, conformance suites (dev-dep only)
│   │   ├── prompts/           # DATA: system-prompt parts + built-in templates
│   │   └── schemas/           # generated JSON Schemas (cargo xtask)
│   ├── providers/             # cargo workspace — connector umbrella
│   │   └── crates/
│   │       ├── providers/     # facade: resolve provider registry, re-exports connectors
│   │       ├── common/        # shared provider client utilities
│   │       ├── anthropic/     # Anthropic Messages API client
│   │       ├── openai/        # OpenAI (and DeepSeek) client
│   │       ├── gemini/        # Google Gemini client
│   │       ├── ollama/        # Ollama local model client
│   │       ├── bedrock/       # AWS Bedrock client
│   │       ├── copilot/       # GitHub Copilot device-flow auth + API client
│   │       └── delegators/    # external-agent connectors (acp, claude-code, copilot,
│   │                          #   cursor, grok, opencode) + shared common
│   ├── search/                # cargo workspace — deep-search plugin
│   │   └── crates/search/     # SearchPlugin: search_web + scrape_page + researcher role
│   └── sdk/                   # cargo workspace — builder API + headless runner
│       └── crates/sdk/        # AgentBuilder + `flex` [[bin]]

License

Dual-licensed under Apache License 2.0 or
MIT, at your option.

Unless you state otherwise, any contribution you intentionally submit for
inclusion in this work, as defined in the Apache-2.0 license, is dual licensed
as above, without additional terms or conditions.