actx (REPL)

When you run actx without any arguments, it drops you into the AgentCTX Interactive REPL (Read-Eval-Print Loop).

The REPL is a unified environment designed to let you natively interact with the CTX language, execute CLI subcommands rapidly, and seamlessly drop down to your host OS shell without changing windows.

Usage

actx

Expected output:

Welcome to AgentCTX REPL. Type 'exit' to quit or 'help' for commands.
You can type CTX statements natively (e.g. ?m list) or run CLI commands.
actx>

Supported Commands

The interactive shell acts as an intelligent multiplexer, handling inputs in the following priority order:

1. AgentCTX CLI Subcommands

Any standard actx subcommand can be run by simply typing the command name directly, with or without a forward slash (/).

actx> status          # Equivalent to 'actx status'
actx> /swarm          # Equivalent to 'actx swarm'
actx> start --compact # Equivalent to 'actx start --compact'

2. Native CTX Syntax

If you type a valid CTX operator (+, -, ?, ~, !, >, ^), the REPL automatically parses the statement into an AST (Abstract Syntax Tree), cryptographically signs the “Human” intent using the Ed25519 WASM sidecar, and processes it through the gateway middleware.

actx> +m "project_status" "We are launching on Tuesday."

📝 Parsed CTX:
{
  "operator": "+",
  "plane": "m",
  "target": "project_status",
  "content": "We are launching on Tuesday."
}

🗣️  Human: Adding project_status to m-plane
   (Signed: ce:7a92b...)

📤 Result:
{
  "ok": true,
  "savings": 218,
  // ...
}

3. External Host Shell Commands

If the command isn’t a CTX statement and isn’t recognized as an internal AgentCTX CLI subcommand, the REPL assumes it is an OS-level shell command. It safely spawns the process using your host’s native shell (powershell on Windows, or standard shell on macOS/Linux).

actx> pwd
/Users/developer/my-agent-project

actx> git status
On branch main
Nothing to commit, working tree clean

Note: cd <directory> is handled natively by the REPL to ensure the underlying Node process context moves correctly along with your prompt.