docs: add trade-off evaluation for openagents-cli rust migration

1

# Architecture Evaluation: Migrating OpenAgents CLI to Rust

2

3

**Date:** 2026-08-25

4

**Author:** OpenAgents Core Team

5

**Scope:** `packages/openagents-cli` (TypeScript / Effect-TS) $\rightarrow$ Full Rust rewrite (`crates/openagents-cli`)

6

7

---

8

9

## Executive Summary

10

11

The `openagents` CLI is currently implemented in TypeScript (`packages/openagents-cli`) using `@effect/platform-node` and `effect` for async concurrency, typed errors, and streaming, alongside cryptographic libraries (`@noble/curves`, `@noble/hashes`, `@scure/bip39`) and terminal interface rendering (`coder-ui.ts`).

12

13

Migrating the CLI from TypeScript/Effect-TS to a native Rust binary presents architectural opportunities and trade-offs. This document outlines the technical, operational, and maintenance trade-offs to guide the migration decision.

14

15

---

16

17

## Current Architecture

18

19

- **Language & Runtime:** TypeScript / Node.js 20+ ESM via `@effect/platform-node`.

20

- **Concurrency & Control Flow:** Effect-TS pipelines for effects, environment management, structured error handling, and terminal lifecycle management.

21

- **Subsystems in Scope:**

22

  - **Coder & Fleet Orchestration:** `coder-*.ts` (multi-lane delegation across Devin, Ox Alpha, Claude Code, Codex, local Ollama, headless subprocess execution, ACP protocol).

23

  - **Interactive TUI Engine:** Custom terminal raw-mode UI, diff renderer, keybinding handlers, box frame layouts (`coder-ui.ts`, `box-*.ts`).

24

  - **Sovereign Identity & Auth:** BIP-39 mnemonic generation, secp256k1 key derivation, token management in OS keychain (`identity-*.ts`, `auth-*.ts`).

25

  - **Forge & API Gateway:** REST/JSON API bindings for issues, pull requests, projects, repositories, forum, and WebSocket event subscribers (`api-*.ts`).

26

27

---

28

29

## Pros: Benefits of Converting to Rust

30

31

### 1. Zero Runtime Dependencies & Instant Cold Startup

32

- **Native Binary:** Eliminates the requirement for users to have Node.js 20+ installed.

33

- **Sub-10ms Startup:** Eliminates V8 engine initialization, JIT warm-up, and module resolution overhead. Essential for CLI commands invoked frequently in scripts, git hooks, and child agents (`openagents auth status`, `openagents issue view`).

34

- **Streamlined `curl | bash` Distribution:** Directly yields static binaries (`x86_64-unknown-linux-musl`, `aarch64-apple-darwin`, `x86_64-pc-windows-msvc`) with zero packaging friction.

35

36

### 2. Predictable Memory Footprint & Resource Efficiency

37

- **Low Memory Overhead:** A compiled Rust binary operates in 5–20 MB of RAM compared to Node.js / V8's baseline 50–150 MB RSS.

38

- **Parallel Fan-out Scaling:** In fleet delegation (`coder-delegate.ts`), orchestrating multiple subprocesses and telemetry streams consumes a fraction of host resources.

39

40

### 3. Mature Systems & Terminal Ecosystem

41

- **Rich CLI & TUI Libraries:** First-class ecosystems for CLI interfaces:

42

  - Argument parsing: `clap` (derive macro, automated shell completions, typed flags).

43

  - TUI Rendering: `ratatui` / `crossterm` for terminal user interfaces and diffing.

44

  - Async I/O: `tokio` for async scheduling and process handling.

45

- **Process & Signal Control:** Exact control over process groups, pseudo-terminals (pty), child process termination, and signal handling (`SIGINT`, `SIGTERM`, `SIGWINCH`) without cross-platform Node.js pty discrepancies.

46

47

### 4. Direct Monorepo Rust Synergy

48

- **Code Sharing with Existing Crates:** The monorepo already maintains Rust crates under `crates/` (`oa-node`, `all-work-contract`, `oa-workroomd`, `openagents-cloud-contract`). A Rust CLI can directly import shared schema types, cryptographic utilities, and protocol contracts without intermediate TypeScript bindings or WASM wrappers.

49

50

### 5. Memory Safety & Strict Concurrency Guarantees

51

- Compiler-enforced concurrency guarantees avoid data races during heavy multi-agent event multiplexing and streaming.

52

53

---

54

55

## Cons: Drawbacks and Costs of Converting to Rust

56

57

### 1. Significant Migration & Rewrite Overhead

58

- **Substantial Code Surface:** `packages/openagents-cli` contains over 30,000+ lines of TypeScript across ~90 files (coder harnesses, ACP protocol integration, forum claims, repository sync, provider settlements, box run pipelines).

59

- **Time to Feature Parity:** A full port requires rewriting all API callers, client state machines, formatting outputs, and comprehensive test suites (`test/*.test.ts`).

60

61

### 2. Loss of Effect-TS Ecosystem Ergonomics

62

- Effect-TS provides unified effect tracking, algebraic data types, layer composition, and runtime fiber management in TypeScript.

63

- While Rust provides `Result<T, E>` and `Option<T>`, mimicking Effect's functional dependency injection and managed service layers requires bespoke architectural patterns in Rust.

64

65

### 3. Developer Friction & Contribution Velocity

66

- Modifying CLI tools in TypeScript allows fast iteration, immediate dynamic inspection, and broad accessibility across JavaScript/TypeScript fullstack developers.

67

- Rust requires stricter type bookkeeping, handling lifetimes/ownership, and dealing with longer compilation/link cycles during CI/CD test runs.

68

69

### 4. Cross-Platform Compilation & CI Release Matrix

70

- Cross-compiling Rust binaries (especially with OpenSSL or C dependencies) requires dedicated cross-compilation runners, musl toolchains, macOS code notarization, and Windows build pipelines.

71

- Node/TypeScript packages publish with minimal build steps to npm.

72

73

---

74

75

## Comparison Matrix

76

77

| Dimension | TypeScript (Current / Effect-TS) | Rust (`crates/openagents-cli`) |

78

| :--- | :--- | :--- |

79

| **Startup Latency** | ~150ms – 350ms (Node boot) | ~3ms – 10ms (Native) |

80

| **Runtime Requirement** | Node.js $\ge$ 20.0.0 | None (Statically linked binary) |

81

| **Memory Consumption** | ~50MB – 120MB RSS | ~5MB – 25MB RSS |

82

| **Distribution Method** | `npm install -g`, `npx` | `curl \| bash`, GitHub Release, `cargo install` |

83

| **Development Velocity**| Rapid iteration, hot TS execution | Strict borrow checker, longer compile times |

84

| **Crate Interop** | Requires WASM / JSON RPC bridges | Direct native crate imports |

85

| **TUI / Subprocess Control** | Node `child_process` / `node-pty` | `crossterm`, `tokio::process`, native pty |

86

87

---

88

89

## Recommended Strategy

90

91

1. **Near-Term (Current Release):**

92

   - Retain TypeScript codebase for immediate velocity.

93

   - Package standalone binaries using Bun single-file executable compiler or Node Single Executable Applications (SEA) to enable the `curl -fsSL https://openagents.com/cli/install.sh | bash` distribution pipeline without requiring Node on user machines.

94

95

2. **Medium-Term (Targeted Rust Migration):**

96

   - Extract performance-critical / system-level components into Rust crates (e.g. `coder` execution engine, credential vaults, pty supervisors).

97

   - Evaluate a full Rust CLI binary under `crates/openagents-cli` once protocol schemas and agent harness APIs stabilize.

Commit

docs: add trade-off evaluation for openagents-cli rust migration

Deploy story

Changed files

Diff

1	+	`# Architecture Evaluation: Migrating OpenAgents CLI to Rust`
2	+
3	+	`Date: 2026-08-25`
4	+	`Author: OpenAgents Core Team`
5	+	Scope: `packages/openagents-cli` (TypeScript / Effect-TS) $\rightarrow$ Full Rust rewrite (`crates/openagents-cli`)
6	+
7	+	`---`
8	+
9	+	`## Executive Summary`
10	+
11	+	The `openagents` CLI is currently implemented in TypeScript (`packages/openagents-cli`) using `@effect/platform-node` and `effect` for async concurrency, typed errors, and streaming, alongside cryptographic libraries (`@noble/curves`, `@noble/hashes`, `@scure/bip39`) and terminal interface rendering (`coder-ui.ts`).
12	+
13	+	`Migrating the CLI from TypeScript/Effect-TS to a native Rust binary presents architectural opportunities and trade-offs. This document outlines the technical, operational, and maintenance trade-offs to guide the migration decision.`
14	+
15	+	`---`
16	+
17	+	`## Current Architecture`
18	+
19	+	- Language & Runtime: TypeScript / Node.js 20+ ESM via `@effect/platform-node`.
20	+	`- Concurrency & Control Flow: Effect-TS pipelines for effects, environment management, structured error handling, and terminal lifecycle management.`
21	+	`- Subsystems in Scope:`
22	+	- Coder & Fleet Orchestration: `coder-*.ts` (multi-lane delegation across Devin, Ox Alpha, Claude Code, Codex, local Ollama, headless subprocess execution, ACP protocol).
23	+	- Interactive TUI Engine: Custom terminal raw-mode UI, diff renderer, keybinding handlers, box frame layouts (`coder-ui.ts`, `box-*.ts`).
24	+	- Sovereign Identity & Auth: BIP-39 mnemonic generation, secp256k1 key derivation, token management in OS keychain (`identity-.ts`, `auth-.ts`).
25	+	- Forge & API Gateway: REST/JSON API bindings for issues, pull requests, projects, repositories, forum, and WebSocket event subscribers (`api-*.ts`).
26	+
27	+	`---`
28	+
29	+	`## Pros: Benefits of Converting to Rust`
30	+
31	+	`### 1. Zero Runtime Dependencies & Instant Cold Startup`
32	+	`- Native Binary: Eliminates the requirement for users to have Node.js 20+ installed.`
33	+	- Sub-10ms Startup: Eliminates V8 engine initialization, JIT warm-up, and module resolution overhead. Essential for CLI commands invoked frequently in scripts, git hooks, and child agents (`openagents auth status`, `openagents issue view`).
34	+	- Streamlined `curl \| bash` Distribution: Directly yields static binaries (`x86_64-unknown-linux-musl`, `aarch64-apple-darwin`, `x86_64-pc-windows-msvc`) with zero packaging friction.
35	+
36	+	`### 2. Predictable Memory Footprint & Resource Efficiency`
37	+	`- Low Memory Overhead: A compiled Rust binary operates in 5–20 MB of RAM compared to Node.js / V8's baseline 50–150 MB RSS.`
38	+	- Parallel Fan-out Scaling: In fleet delegation (`coder-delegate.ts`), orchestrating multiple subprocesses and telemetry streams consumes a fraction of host resources.
39	+
40	+	`### 3. Mature Systems & Terminal Ecosystem`
41	+	`- Rich CLI & TUI Libraries: First-class ecosystems for CLI interfaces:`
42	+	- Argument parsing: `clap` (derive macro, automated shell completions, typed flags).
43	+	- TUI Rendering: `ratatui` / `crossterm` for terminal user interfaces and diffing.
44	+	- Async I/O: `tokio` for async scheduling and process handling.
45	+	- Process & Signal Control: Exact control over process groups, pseudo-terminals (pty), child process termination, and signal handling (`SIGINT`, `SIGTERM`, `SIGWINCH`) without cross-platform Node.js pty discrepancies.
46	+
47	+	`### 4. Direct Monorepo Rust Synergy`
48	+	- Code Sharing with Existing Crates: The monorepo already maintains Rust crates under `crates/` (`oa-node`, `all-work-contract`, `oa-workroomd`, `openagents-cloud-contract`). A Rust CLI can directly import shared schema types, cryptographic utilities, and protocol contracts without intermediate TypeScript bindings or WASM wrappers.
49	+
50	+	`### 5. Memory Safety & Strict Concurrency Guarantees`
51	+	`- Compiler-enforced concurrency guarantees avoid data races during heavy multi-agent event multiplexing and streaming.`
52	+
53	+	`---`
54	+
55	+	`## Cons: Drawbacks and Costs of Converting to Rust`
56	+
57	+	`### 1. Significant Migration & Rewrite Overhead`
58	+	- Substantial Code Surface: `packages/openagents-cli` contains over 30,000+ lines of TypeScript across ~90 files (coder harnesses, ACP protocol integration, forum claims, repository sync, provider settlements, box run pipelines).
59	+	- Time to Feature Parity: A full port requires rewriting all API callers, client state machines, formatting outputs, and comprehensive test suites (`test/*.test.ts`).
60	+
61	+	`### 2. Loss of Effect-TS Ecosystem Ergonomics`
62	+	`- Effect-TS provides unified effect tracking, algebraic data types, layer composition, and runtime fiber management in TypeScript.`
63	+	- While Rust provides `Result<T, E>` and `Option<T>`, mimicking Effect's functional dependency injection and managed service layers requires bespoke architectural patterns in Rust.
64	+
65	+	`### 3. Developer Friction & Contribution Velocity`
66	+	`- Modifying CLI tools in TypeScript allows fast iteration, immediate dynamic inspection, and broad accessibility across JavaScript/TypeScript fullstack developers.`
67	+	`- Rust requires stricter type bookkeeping, handling lifetimes/ownership, and dealing with longer compilation/link cycles during CI/CD test runs.`
68	+
69	+	`### 4. Cross-Platform Compilation & CI Release Matrix`
70	+	`- Cross-compiling Rust binaries (especially with OpenSSL or C dependencies) requires dedicated cross-compilation runners, musl toolchains, macOS code notarization, and Windows build pipelines.`
71	+	`- Node/TypeScript packages publish with minimal build steps to npm.`
72	+
73	+	`---`
74	+
75	+	`## Comparison Matrix`
76	+
77	+	\| Dimension \| TypeScript (Current / Effect-TS) \| Rust (`crates/openagents-cli`) \|
78	+	`\| :--- \| :--- \| :--- \|`
79	+	`\| Startup Latency \| ~150ms – 350ms (Node boot) \| ~3ms – 10ms (Native) \|`
80	+	`\| Runtime Requirement \| Node.js $\ge$ 20.0.0 \| None (Statically linked binary) \|`
81	+	`\| Memory Consumption \| ~50MB – 120MB RSS \| ~5MB – 25MB RSS \|`
82	+	\| Distribution Method \| `npm install -g`, `npx` \| `curl \\| bash`, GitHub Release, `cargo install` \|
83	+	`\| Development Velocity\| Rapid iteration, hot TS execution \| Strict borrow checker, longer compile times \|`
84	+	`\| Crate Interop \| Requires WASM / JSON RPC bridges \| Direct native crate imports \|`
85	+	\| TUI / Subprocess Control \| Node `child_process` / `node-pty` \| `crossterm`, `tokio::process`, native pty \|
86	+
87	+	`---`
88	+
89	+	`## Recommended Strategy`
90	+
91	+	`1. Near-Term (Current Release):`
92	+	`- Retain TypeScript codebase for immediate velocity.`
93	+	- Package standalone binaries using Bun single-file executable compiler or Node Single Executable Applications (SEA) to enable the `curl -fsSL https://openagents.com/cli/install.sh \| bash` distribution pipeline without requiring Node on user machines.
94	+
95	+	`2. Medium-Term (Targeted Rust Migration):`
96	+	- Extract performance-critical / system-level components into Rust crates (e.g. `coder` execution engine, credential vaults, pty supervisors).
97	+	- Evaluate a full Rust CLI binary under `crates/openagents-cli` once protocol schemas and agent harness APIs stabilize.