contd

English | 简体中文

contd makes interactive CLI programs usable in an async way.

It is built for flows where plain run-until-exit CLIs: debuggers, REPLs, setup wizards, prompts, TUIs, and time-consuming commands.

Showcase

showcase.mp4

Using contd with gdb to solve the CS:APP bomb lab in resumable attach steps.

Platform Support

• Supported: Linux, macOS
• Linux has stronger boundary detection (proc syscall/fd inspection), so stdin-wait recognition is more accurate.
• macOS uses heuristic detection and screen-stability checks, so behavior can be slightly less precise on some workloads.

Install

1. Install CLI:

curl -fsSL https://raw.githubusercontent.com/werifu/contd/main/install.sh | bash

2. Install skill for all supported agents:

npx -y skills@latest add werifu/contd-skill --skill contd --yes --global

3. Verify:

contd --help

Skill repo: https://github.com/werifu/contd-skill

What You Get

• Keep one interactive process alive across many calls
• Drive it via run + repeated attach
• Get deterministic return points (ready for input, timed out, exited)
• Optional --json mode for agent/tool integration

How it works

+---------+       run        +-------+    fork       +------------------+
|         |----------------->|       |-------------> | interactive CLI  |
|         |                  |       |               +------------------+
| Agent   |                  | contd |   wait for input       |
|         |<-----------------|       |<-----------------------|
+---------+                  +-------+                        |
                                                              |
+---------+                  +-------+                        |
|         |   attach+input   |       |      input             |
|         |----------------->|       |----------------------->|
| Agent   |                  | contd |                        |
|         |<-----------------|       |<-- output/input wait --|
+---------+                  +-------+                        |
                                                              v

Quick Start

# 1) Start a managed interactive session
$ contd run -- lldb-20 /path/to/contd

# 2) Continue the same live session by ID (or unique prefix)
$ contd attach 5e --input "b main\n"
$ contd attach 5e --input "run\n"
$ contd attach 5e --input "step\n"

# 3) Inspect or clean up sessions
$ contd list
$ contd kill 5e
$ contd clean

Defaults:

• run hard timeout: 10s
• attach hard timeout: 300s
• override with --yield_timeout <duration> (hard deadline)

LLDB Example (Human Output)

$ contd run -- lldb-20 /path/to/contd
ready for input
id: 5e25da868137dd1b499db90ab0446331
pid: 20049

output:
(lldb) target create "/path/to/contd"
Current executable set to '/path/to/contd' (x86_64).
(lldb)

$ contd attach 5e --input "b main\n"
ready for input
id: 5e25da868137dd1b499db90ab0446331
pid: 20049

output:
b main
Breakpoint 1: 2 locations.
(lldb)

$ contd attach 5e --input "run\n"
ready for input
id: 5e25da868137dd1b499db90ab0446331
pid: 20049

output:
run
Process 20378 launched: '/path/to/contd' (x86_64)
Process 20378 stopped
* thread #1, name = 'contd', stop reason = breakpoint 1.2
    frame #0: 0x00005555556f6a30 contd`main
(lldb)

JSON Integration

Use --json when parsing events in agents/tools:

$ contd --json run -- /bin/cat
{"event":"session_waiting_input","session_id":"...","output":"","detector":{...}}

Common events:

• session_waiting_input
• session_steady_input
• session_yield_timeout
• session_exited
• error

Commands

• contd run -- <cmd> [args...]
• contd attach <session_id_or_prefix> [--input <text>]
• contd kill <session_id_or_prefix>
• contd list [session_id_or_prefix]
• contd gc
• contd clean

Global flags:

• --json
• --verbose
• --raw-pty (run/attach)

Architecture and Internals

Design details (broker model, Linux boundary detection, RPC/compatibility):

• ARCHITECTURE.md

Development

cargo test --features test-bins
cargo fmt

Integration tests are OS-scoped:

• Linux runs tests/integration_linux.rs
• macOS runs tests/integration_macos.rs

License

Apache-2.0. See LICENSE.