CodeFlow-harness

An Agent Harness for concurrent tasks and multi-turn conversations.

Schedule concurrent tasks and multi-turn sessions with context governance, Checkpoint / Resume, an SRT shell sandbox, and regression evaluation. CLI, native TUI, Gateway, scheduled jobs, and messaging channels share one Runtime and one set of execution boundaries.

Quick start · SRT shell sandbox · First-use guide · Feishu · Agent install contract · 中文

---

CodeFlow-harness is an open-source Agent Harness for concurrent tasks and multi-turn conversations. It makes task execution replayable and evaluable, with explicit tool-execution boundaries. Session queues and concurrency limits preserve tool order within a conversation while allowing different sessions to run concurrently. Checkpoint / Resume supports interrupted-task recovery, and Context management budgets and compresses model input.

CLI, native TUI, Gateway, scheduled jobs, and messaging channels share one Runtime. It handles scheduling and cancellation, Context assembly, tool execution, Session persistence, tracing, and delivery. Regression evaluation covers scheduling, model-call cost, Context and Memory, tool execution, and recovery. Built-in project-level turn memory works without an external backend; optional Memory backends can add long-term recall, and this release does not bundle an external Memory implementation. Shell commands can run in Anthropic's SRT operating-system sandbox or BoxLite MicroVMs. SRT fails closed when its runtime or platform isolation is unavailable.

Context management follows CodeFlow's layered approach. Before each model call, it budgets the prefix, Memory, Skills, relevant memories, and history while preserving the current user request. As history pressure rises, it first snips older tool results, then prioritizes recent turns, and at high pressure summarizes older history behind a saved boundary. Completed turns also produce local summaries. New requests retrieve up to three relevant summaries through semantic search and BM25, then merge rankings with reciprocal rank fusion (RRF). Install the optional semantic-memory extra for FastEmbed; if the package or model is unavailable, retrieval falls back to TF-IDF character vectors plus BM25. Summaries live under the project's Runtime state directory in context_memory/.

flowchart LR
    U["You"] --> H["CLI · TUI · Gateway · Cron · Feishu"]
    H --> S["Spine"]
    S --> T["Turn Runner"]
    T --> A["Agent Loop"]
    A <--> C["Context"]
    A <--> M["Optional Memory"]
    A <--> X["Tools · MCP · Sandbox"]
    A <--> P["Providers"]
    T --> E["Session · Tracing · Delivery"]

Loading

Evaluation highlights

Selected project measurements from separate workloads and baselines; comparisons apply only within each stated test.

From install to a real reply

CodeFlow requires Python 3.12. The native TUI uses Node.js 22; the installer can provision a private Node runtime when the system version is missing or too old.

Clone the public repository and run the installer from the checkout:

git clone https://github.com/pei711/CodeFlow-harness.git
cd CodeFlow-harness
./install.sh

Windows PowerShell:

git clone https://github.com/pei711/CodeFlow-harness.git
Set-Location CodeFlow-harness
.\install.ps1

The installer resolves CodeFlow from GitHub Releases and defaults to China-hosted Python and Node.js mirrors. A private repository or restricted Release requires CODEFLOW_GITHUB_TOKEN. You can also set CODEFLOW_WHEEL_URL to a trusted wheel URL.

Installer control	Purpose
CODEFLOW_GITHUB_TOKEN	read a private GitHub Release
CODEFLOW_WHEEL_URL	install a trusted CodeFlow wheel directly
CODEFLOW_PYPI_INDEX	override the Python package index
CODEFLOW_NODE_MIRROR	override the Node.js download mirror
CODEFLOW_NODE_CHECKSUM_BASE	override the Node.js checksum source
CODEFLOW_NPM_REGISTRY	override the npm registry
CODEFLOW_UV_INSTALL_URL	override the uv installer URL

Configure CodeFlow inside the repository where the agent will work:

cd /path/to/your-project
codeflow onboard --skip-memory

The four-step wizard follows the first result you can verify:

LLM credentials -> Memory explicitly off -> first real Turn
                -> run location -> optional message channel

This release does not contain an external Memory implementation, so --skip-memory is the supported path. CodeFlow records memory.backend = null; it does not pretend that a missing backend is healthy.

After onboarding:

codeflow
codeflow run -m "Map the main request path in this repository"
codeflow doctor --probe

codeflow doctor --probe sends a real model request. A static configuration check or a skipped probe does not prove that the Provider returned a reply.

Shell commands can use BoxLite MicroVMs or Anthropic's SRT operating-system sandbox. See the SRT shell sandbox guide for setup, policy scope, and runtime limitations.

See the first-use guide for private Release authentication, non-interactive setup, exact acceptance checks, and recovery paths.

What CodeFlow owns

What you need	What CodeFlow does
One agent across several surfaces	CLI, TUI, Gateway, Cron, and Channels submit the same Turn contract
Context that does not become a prompt dump	Context is retrieved, budgeted, and assembled before each model call
Tools with explicit boundaries	Filesystem, Shell, Web, MCP, messaging, and Subagents share confirmation and Sandbox controls
Recoverable conversations	Sessions persist independently from the current terminal process
Debuggable outcomes	Tracing, Provider usage, delivery state, and evaluation evidence remain separate records
Controlled improvement	Evolver produces candidates and evidence; activation and rollback remain explicit operator actions

Connect Feishu

CodeFlow uses Feishu's WebSocket long connection, so you do not need a public IP or webhook domain.

codeflow channels enable feishu \
  --app-id "cli_xxxxxxxxxxxxxxxx" \
  --app-secret "$FEISHU_APP_SECRET"

cd /path/to/your-project
codeflow gateway --workspace "$PWD" --verbose

The Feishu app still needs bot capability, message permissions, im.message.receive_v1, and a published application version. Follow the Feishu guide before testing an inbound message. Saving channel configuration does not prove that live delivery works.

Commands worth remembering

Goal	Command
Configure CodeFlow and run the first Turn	codeflow onboard --skip-memory
Open the native TUI	codeflow
Execute one Turn	codeflow run -m "..."
Check Runtime and Provider health	codeflow doctor --probe
Inspect installed Plugins	codeflow plugins
Manage message channels	codeflow channels ...
Serve enabled channels	codeflow gateway --workspace /path/to/project
Manage scheduled work	codeflow cron ...
Inspect Sessions and Tracing	codeflow sessions ... / codeflow tracing
Run operator-controlled evolution	codeflow evolve check|run|status|finalize

State and security

Scope	Default location
Global configuration and Runtime data	~/.codeflow
Foreground project	current directory
Foreground project state	~/.codeflow/projects/<project-id>
Gateway Workspace	explicit --workspace, otherwise ~/.codeflow/workspace

Normal startup keeps CodeFlow state outside the repository. Executable Plugins are loaded only from CodeFlow's bundled set, operator-managed ~/.codeflow/plugins/, and installed codeflow.plugins entry points. A checkout's .codeflow/plugins/ directory is not an automatic startup source.

Read the Memory boundary and troubleshooting guide before changing a backend or handing the installation to another operator.

Release repository boundary

This repository contains publishable source, deterministic tests, reviewed benchmark code and fixtures, installers, onboarding material, and legal notices. It excludes development plans, raw run artifacts, credentials, private environment instructions, and unpublished external Memory artifacts.

Public benchmark results apply only to the frozen workload and verifier named in their documents. They are not production SLAs. Start with the evaluation index and benchmarks/.

Contributing

Start with an issue labeled good-first-issue. Every claimable issue names its target branch, relevant files, scope, and acceptance command. Comment on the issue before starting, then submit one pull request for that issue.

See the contribution guide for branch selection, local verification, and safety requirements. Remove tokens, private keys, internal addresses, and personal data from public issue reports.

Build and verify

uv sync --frozen --extra dev --dev
npm ci
npm ci --prefix ui-tui
make check
make codeflowbench-smoke
CODEFLOW_RELEASE_OUTPUT=/absolute/empty/output make release-dist

CodeFlow is pre-1.0. Interfaces can change. make check verifies the retained release tree; it does not replace a real Provider or channel smoke test.

License

CodeFlow is licensed under Apache License 2.0. See LICENSE, NOTICES.md, and LICENSES/ for attribution.