JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.
CLI / Channel Control Commands
JiuwenSwarm supports special prefix commands to control sessions and modes. These commands are parsed by the Gateway's MessageHandler and are not sent to the Agent.
Supported Channels
The following IM channels support control commands:
feishuxiaoyidingtalkwhatsappwechat
1. /new_session — New Session ID
Behavior
- Generates a new
session_idfor the current channel, formatted as{channel_type}_{ms_timestamp_hex}_{random_hex} - All subsequent chat messages from this channel will be forced to use the new
session_id
Usage
Send in a supported channel:
/new_session

The Gateway will:
- Intercept this message (not forwarded to the Agent)
- Cancel any tasks currently running in the session
- Generate a new
session_idfor thatchannel_id - Reply with a system message, e.g.:
[Received CLI command], session_id changed to feishu_17f2b4b32e0_ab12cd
2. /mode — Switch Channel Mode
Behavior
Sets the working mode for the current channel. The Agent uses this when constructing prompts and behavior strategies.
Primary Modes (mapped to secondary modes):
| Command | Maps to | Description |
|---|---|---|
/mode agent |
agent.plan |
Agent mode, planning/explanation/decomposition |
/mode code |
code.normal |
Code mode, Agent interacts via code execution tools |
/mode team |
team |
Team mode |
Direct Secondary Modes:
| Command | Description |
|---|---|
/mode agent.plan |
Agent mode + planning style (default) |
/mode agent.fast |
Agent mode + auto-execution style |
/mode code.normal |
Code mode + direct execution style (default) |
/mode code.team |
Code mode + team style |
Note: this table is the Gateway controlled-channel whitelist. The TUI local
/modecommand also supports/mode plan(equivalent toagent.plan) and/mode team.normal(equivalent toteam); those forms are not recognized by Gateway controlled channels.
Usage
/mode agent
The Gateway will:
- Intercept this message
- Cancel tasks in the current session (if mode changes)
- Update
ChannelControlState.mode - Reply with a system message, e.g.:
[Received CLI command], mode changed to code.normal
3. /switch — Switch Secondary Mode
Behavior
Switches secondary style within the current primary mode, more concise than /mode.
| Command | When in agent mode | When in code mode |
|---|---|---|
/switch plan |
→ agent.plan |
Not supported |
/switch fast |
→ agent.fast |
Not supported |
/switch normal |
Not supported | → code.normal |
/switch team |
Not supported | → code.team |
The TUI source contains a
/switchimplementation, but the default TUI command registry does not currently register it. In TUI, prefer/mode ...or/planfor sub-mode switching.
Usage
/switch plan
4. /skills list — List Available Skills
Behavior
Queries the currently available skill list.
Usage
/skills list
The Gateway will call skills.list and reply with the skill list as a notification.
5. /branch — Fork Session
Behavior
Forks a new session from the current one, preserving the original conversation history. Useful for exploring new directions without affecting the original session.
Usage
/branch
Or with a custom name:
/branch fix login issue
The Gateway will:
- Call
session.forkto create a new session - Switch to the new session
- Reply with a message, e.g.:
[Received /branch command] Session "fix login issue" forked, now switched to new session.
6. /rewind — Rewind Conversation
Behavior
Rewinds the current session to a specified turn, deleting that turn and all subsequent conversation records.
Usage
First send the rewind request:
/rewind 3
The Gateway will reply with a confirmation prompt:
[Received /rewind 3 command] Confirm rewind to turn 3?
This operation is irreversible and will delete turn 3 and all subsequent conversations.
Please reply /rewind confirm 3 to confirm, or /rewind cancel to cancel.
Note: Rewind does not affect manually edited files or commands executed via bash.
Confirm execution:
/rewind confirm 3
Cancel operation:
/rewind cancel
7. TUI: /workspace_dir — Workspace Path for Outbound Requests
Scope: Terminal UI (jiuwenswarm-tui) only; parsed locally, not by the Gateway control pipeline.
Behavior
/workspace_diror/workspace_dir get: show the saved workspace directory (if any)./workspace_dir set <path>: save a path (spaces allowed). Example:/workspace_dir set C:\Projects\my-app/workspace_dir clear: clear the saved value.- Alias:
/workspace-dir.
Persistence
- Stored as a single-line file:
~/.jiuwenswarm/tui-workspace-dir.
Gateway / Agent
- When a non-empty path is set, TUI includes
workspace_dirin the WebSocketparamsfor fire-and-forget requests built bysendEventOnly(e.g.chat.send), so Gateway and AgentServer can read it fromMessage.params/AgentRequest.params. Downstream usage depends on the agent and extensions.
8. /compact — Context Compression
Scope: TUI only; triggers context compression via AgentServer.
Behavior
- Actively triggers context compression to clean up conversation history while keeping summary information in context.
- TUI sends
command.compactrequest to AgentServer.
Usage
/compact
Return Values
busy: Compression is already in progress, please try again later.compressed: Compression successful, displays token count before/after compression and savings percentage.noop: No compression needed, context is already optimized.
Configuration Notes
- Mode is stored per channel (
channel_id→mode). All subsequent messages on that channel will automatically include the current mode. default_modecan be set inconfig.yamlas the initial value;MessageHandlerreads it on startup./new_sessionand/modechanges will automatically cancel tasks currently running in the session.
Terminal CLI: jiuwenswarm chat
Starting from v0.2.3, JiuwenSwarm provides a first-party command-line chat entry point to interact with JiuwenSwarm directly from the terminal.
Quick Start
# Start Gateway and AgentServer (if not running)
jiuwenswarm-start app
# Send a message
jiuwenswarm chat "Hello, introduce yourself"
jiuwenswarm chat calls JiuwenSwarm's runtime through the Gateway's /tui WebSocket route (channel_id="tui"), sharing the same MessageHandler and AgentServer path as the TUI.
Basic Usage
| Command | Description |
|---|---|
jiuwenswarm chat "hello" |
Send a single message |
jiuwenswarm chat check the repo and suggest |
Multi-word args joined into one prompt |
echo "analyze main.py" | jiuwenswarm chat |
Pipe stdin |
jiuwenswarm chat |
No args + interactive TTY → enter REPL mode |
Single-message, piped, and JSON/JSONL invocations are non-interactive, so the
runtime does not expose the ask_user tool to the Agent. Use REPL mode without
a prompt argument when the Agent needs to ask follow-up questions or present options.
Options
| Option | Default | Description |
|---|---|---|
--mode <mode> |
code.normal |
Execution mode, see Modes |
--session <id> |
Auto-generated | Reuse or create a named session id |
--cwd <path> |
Current dir | Working directory for file mentions and agent context |
--project-dir <path> |
--cwd |
Project identity for session and agent cache |
--trusted-dir <path> |
--project-dir |
Trusted directory (repeatable) |
--gateway-url <url> |
ws://127.0.0.1:19001/tui |
Explicit Gateway WebSocket URL |
--name <instance> |
— | Named instance for env isolation |
--dotenv <path> |
— | Path to .env file |
--json |
— | Print one final JSON object |
--jsonl |
— | Print each Gateway event frame as JSON Lines |
--show-reasoning |
— | Include reasoning output (to stderr) |
--show-tools |
— | Include compact tool call/result status (to stderr) |
--timeout <seconds> |
— | Total response timeout in seconds |
Modes (--mode)
Supported mode values match those in Modes and TUI /mode command:
| Mode | Alias | Description |
|---|---|---|
code.normal |
code |
Default, code normal mode |
code.plan |
— | Code planning mode |
code.team |
— | Code team mode |
agent.plan |
agent |
Agent planning mode |
agent.fast |
— | Agent fast mode |
team |
— | Team mode |
# Using aliases
jiuwenswarm chat --mode agent "help me plan"
jiuwenswarm chat --mode code "help me analyze the code"
# Using canonical values
jiuwenswarm chat --mode code.plan "design a user system"
Session Reuse
# First: specify a session name
jiuwenswarm chat --session project-a "analyze the project architecture"
# Follow-up: reuse the same session, preserving context
jiuwenswarm chat --session project-a "any improvement suggestions?"
# Without --session, auto-generates cli-YYYYMMDD-HHMMSS-xxxxxxxx
REPL Mode
Run without a prompt argument to enter multi-turn conversation:
jiuwenswarm chat
# Session: cli-20260616-120500-abc12345
# > show me the files in the current directory
# > analyze main.py
# > /exit
All messages in REPL mode share the same session, maintaining continuous context.
Exit the REPL with any of:
/exit,/quit, or/qCtrl+D(Unix) /Ctrl+Z+Enter (Windows)Ctrl+Cat the input prompt
Loading Spinner
While waiting for the first response, a dynamic loading indicator displays on stderr:
✢ analyzing (3s)
- 12-frame ping-pong animation:
␣ · ✢ ✳ ✶ ✻ ✽forward then reverse - Random verb per turn: analyzing, thinking, planning, exploring, searching, reading, computing, processing, generating, understanding, writing, compiling, checking, optimizing, learning
- Elapsed timer: shows after 1 second
- Stall detection: glyph turns red after 3s of no new content
- Auto-clears on first delta
Output Modes
| Mode | Flag | Description |
|---|---|---|
| Human-readable (default) | — | Stream deltas to stdout |
| JSON | --json |
Buffer all events, output one final JSON object |
| JSONL | --jsonl |
Output each event frame as a JSON Line |
# JSON output
jiuwenswarm chat --json "analyze README"
# → {"ok": true, "content": "..."}
# JSONL output (pipe-friendly)
jiuwenswarm chat --jsonl "analyze README" | jq
Interrupts
| Action | Behavior |
|---|---|
| First Ctrl+C | Sends chat.interrupt to Agent, graceful cancel. In REPL, stays in the loop for the next prompt |
| Second Ctrl+C | Force exit (exit code 130) |
Windows note:
loop.add_signal_handleris not supported on Windows. The CLI falls back tosignal.signal(SIGINT, ...)so Ctrl+C still triggers graceful cancel (sendschat.interrupt) instead of raising an unhandledKeyboardInterrupt. Two rapid Ctrl+C presses force-exit on Windows as well.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Agent returned an error |
| 2 | CLI usage or invalid mode |
| 3 | Gateway unavailable |
| 4 | The current invocation does not support interactive input |
| 130 | Interrupted by user |
Relationship with TUI
jiuwenswarm chat reuses the TUI's /tui route (channel_id="tui"), sharing the same MessageHandler and AgentServer pipeline. Only one TUI/CLI connection per channel_id="tui" is active at a time — opening the TUI while jiuwenswarm chat is running (or vice versa) will replace the previous WebSocket client on that channel. The first version of the terminal CLI does not aim to replicate all TUI slash commands.