Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

docs: update README, CLI docs (doctor, in-chat-commands), integrations (spotify, sub-agents) and source files

Salman Qureshid8e487bd4f50
diff --git a/README.md b/README.md
index 94d9d86a..e5402387 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,7 @@ To reconfigure later (change keys, name, settings):
```bash
mercury doctor
+mercury doctor --platform
```
## Why Mercury?
@@ -116,6 +117,7 @@ In daemon mode, Telegram becomes your primary channel — CLI is log-only since
| `mercury stop` | Stop a background process |
| `mercury logs` | View recent daemon logs |
| `mercury doctor` | Reconfigure setup (name, providers, channels, permissions defaults) |
+| `mercury doctor --platform` | Show cross-platform terminal/daemon compatibility diagnostics |
| `mercury setup` | Re-run the setup wizard |
| `mercury status` | Show config and daemon status |
| `mercury help` | Show full manual |
@@ -152,6 +154,8 @@ Type these during a conversation — they don't consume API tokens. Work on both
| `/view` | Toggle progress view (balanced/detailed) |
| `/view balanced` | Set compact progress view |
| `/view detailed` | Set full progress view |
+| `/code agent <task>` | Delegate a coding task to a sub-agent in background |
+| `/ws exit` | Exit workspace IDE mode back to general chat |
| `/tasks` | List scheduled tasks |
| `/memory` | View and manage second brain memory |
| `/unpair` | Telegram: reset all access |
@@ -176,6 +180,21 @@ Type these during a conversation — they don't consume API tokens. Work on both
| **CLI** | Ink TUI, startup permission mode picker, interactive permission prompts (arrow keys + Enter; Y/N/A shortcuts), progress views (balanced/detailed), real-time streaming |
| **Telegram** | HTML formatting, editable streaming messages, file uploads, typing indicators, multi-user access with admin/member roles |
+### Workspace/Coding Shortcuts (CLI)
+
+- `Ctrl+P` → switch to Plan mode
+- `Ctrl+X` → switch to Execute mode
+- `Esc` or `Ctrl+Q` → exit workspace to general chat
+- `Ctrl+V` → toggle progress view (`/view` is fallback when terminal intercepts Ctrl+V)
+
+### Spotify UI Notes (CLI)
+
+- Spotify deck supports keyboard shortcuts: `N` next, `P` previous, `+/-` volume, `Z` now playing.
+- Inline album art is optional and safe-gated:
+ - Enable with `MERCURY_SPOTIFY_ART=1`
+ - Currently renders only in local iTerm sessions
+ - Automatically falls back to text-only UI in SSH/mobile/light terminals
+
### Telegram Access
Mercury uses an **organization access model** with admins and members.
diff --git a/src/index.ts b/src/index.ts
index 2bc9b169..cc501465 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1035,6 +1035,44 @@ function autoDaemonize(): void {
console.log('');
}
+function runPlatformDoctor(): void {
+ const daemon = getDaemonStatus();
+ const termProgram = process.env.TERM_PROGRAM || 'unknown';
+ const term = process.env.TERM || 'unknown';
+ const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+ const rawModeSupported = Boolean(process.stdin.isTTY && typeof (process.stdin as NodeJS.ReadStream).setRawMode === 'function');
+ const sshSession = Boolean(process.env.SSH_CONNECTION || process.env.SSH_TTY);
+ const ci = process.env.CI === 'true';
+ const canInlineArt = termProgram === 'iTerm.app' && !sshSession && !ci;
+
+ console.log('');
+ console.log(chalk.bold.cyan(' Mercury Platform Doctor'));
+ console.log(chalk.dim(' Cross-platform runtime compatibility report'));
+ console.log('');
+ console.log(` OS: ${chalk.white(process.platform)} (${process.arch})`);
+ console.log(` Node.js: ${chalk.white(process.version)} (required >= 20)`);
+ console.log(` Terminal program: ${chalk.white(termProgram)}`);
+ console.log(` TERM: ${chalk.white(term)}`);
+ console.log(` Interactive TTY: ${isTTY ? chalk.green('yes') : chalk.yellow('no')}`);
+ console.log(` Raw mode support: ${rawModeSupported ? chalk.green('yes') : chalk.yellow('no')}`);
+ console.log(` SSH session: ${sshSession ? chalk.yellow('yes') : chalk.green('no')}`);
+ console.log(` CI environment: ${ci ? chalk.yellow('yes') : chalk.green('no')}`);
+ console.log(` Daemon: ${daemon.running ? chalk.green(`running (PID: ${daemon.pid})`) : chalk.dim('not running')}`);
+ console.log(` Spotify inline art: ${canInlineArt ? chalk.green('supported (iTerm local)') : chalk.dim('disabled/fallback mode')}`);
+ console.log('');
+ console.log(chalk.bold.white(' Keybinding Notes'));
+ console.log(` • View toggle: ${chalk.white('Ctrl+V')} (fallback: ${chalk.white('/view')})`);
+ console.log(` • Workspace exit: ${chalk.white('Esc')} or ${chalk.white('Ctrl+Q')} (fallback: ${chalk.white('/ws exit')})`);
+ console.log(` • Code mode switch: ${chalk.white('Ctrl+P')} plan, ${chalk.white('Ctrl+X')} execute`);
+ console.log('');
+
+ if (!rawModeSupported) {
+ console.log(chalk.yellow(' Warning: Raw mode is unavailable; interactive Ink input may be limited in this terminal.'));
+ console.log(chalk.dim(' Try a local terminal session with TTY support for the best experience.'));
+ console.log('');
+ }
+}
+
async function runAgent(isDaemon: boolean = false): Promise<void> {
let config = loadConfig();
config = ensureCreatorField(config);
@@ -1426,7 +1464,12 @@ program
program
.command('doctor')
.description('Reconfigure Mercury setup (name, providers, channels, permissions defaults)')
- .action(async () => {
+ .option('--platform', 'Show platform compatibility diagnostics')
+ .action(async (opts) => {
+ if (opts.platform) {
+ runPlatformDoctor();
+ return;
+ }
if (isSetupComplete()) {
await configure(loadConfig());
} else {
diff --git a/src/utils/manual.ts b/src/utils/manual.ts
index 14fe8339..edf547a4 100644
--- a/src/utils/manual.ts
+++ b/src/utils/manual.ts
@@ -75,6 +75,7 @@ export function getManual(): string {
['mercury stop', 'Stop a background process'],
['mercury logs', 'Show recent daemon logs'],
['mercury doctor', 'Reconfigure settings (Enter keeps current)'],
+ ['mercury doctor --platform', 'Show cross-platform terminal/daemon compatibility diagnostics'],
['mercury setup', 'Re-run the setup wizard'],
['mercury status', 'Show config and daemon status'],
['mercury telegram list', 'Show Telegram admins, members, and pending requests'],
@@ -138,8 +139,10 @@ export function getManual(): string {
['/code execute', 'Switch to execute mode (implement plan step by step)'],
['/code build', 'Alias of execute mode for build-focused coding'],
['/code workspace', 'Open current directory in workspace IDE mode'],
+ ['/code agent <task>', 'Delegate a coding task to a sub-agent in background'],
['/code off', 'Exit programming mode'],
['/code toggle', 'Cycle through: off → plan → execute → off'],
+ ['/ws exit', 'Exit workspace IDE mode back to general chat'],
['/ws open <path>', 'Open a workspace directory in IDE mode'],
['/ws refresh', 'Refresh file tree + git status panel'],
['/ws stage <file|all>', 'Stage a file or all changes'],
diff --git a/website/docs/cli-commands/doctor.mdx b/website/docs/cli-commands/doctor.mdx
index 089e5ad3..7144bc4a 100644
--- a/website/docs/cli-commands/doctor.mdx
+++ b/website/docs/cli-commands/doctor.mdx
@@ -12,4 +12,22 @@ title: Doctor (Reconfigure)
```bash
mercury doctor
-```
\ No newline at end of file
+```
+
+## Platform Diagnostics
+
+Use `--platform` to run a non-destructive compatibility check for your current environment:
+
+```bash
+mercury doctor --platform
+```
+
+This prints:
+
+- OS + architecture
+- Node.js version
+- Terminal + TTY/raw-mode capability
+- SSH/CI detection
+- Daemon status
+- Spotify inline-art support status
+- Keybinding fallbacks (`/view`, `/ws exit`, etc.)
diff --git a/website/docs/cli-commands/in-chat-commands.mdx b/website/docs/cli-commands/in-chat-commands.mdx
index c995d006..ff7c45f2 100644
--- a/website/docs/cli-commands/in-chat-commands.mdx
+++ b/website/docs/cli-commands/in-chat-commands.mdx
@@ -28,10 +28,15 @@ Type these during a conversation with Mercury. Most work in both CLI and Telegra
| `/budget reset` | Reset usage to zero |
| `/budget set <n>` | Change daily token budget |
| `/permissions` | Change permission mode (Ask Me / Allow All) — Telegram only |
+| `/view` | Toggle progress view (balanced/detailed) |
+| `/view balanced` | Set compact progress view |
+| `/view detailed` | Set full progress view |
+| `/code agent <task>` | Delegate a coding task to a sub-agent in the background |
+| `/ws exit` | Exit workspace IDE mode back to general chat |
| `/tasks` | List scheduled tasks |
| `/memory` | View and manage second brain memory |
| `/unpair` | Telegram only: reset all access, new users can /start again |
:::info Telegram pairing and access
Telegram stays private 1:1 only. The first user sends `/start`, receives a pairing code in Telegram, and you approve that code from the CLI during setup. Later Telegram users also send `/start`, appear as pending requests, and can then be approved or rejected from the CLI `/telegram` menu.
-:::
\ No newline at end of file
+:::
diff --git a/website/docs/integrations/spotify.mdx b/website/docs/integrations/spotify.mdx
index f0aa17e2..d1278ebe 100644
--- a/website/docs/integrations/spotify.mdx
+++ b/website/docs/integrations/spotify.mdx
@@ -142,6 +142,24 @@ The `/spotify player` command launches an interactive arrow-key player in your t
Every action shows real-time feedback with track info and a progress bar.
+### Player shortcuts
+
+Inside the Spotify player (CLI):
+
+- `N` → next track
+- `P` → previous track
+- `+` / `-` → volume up/down by 10%
+- `Z` → refresh now playing
+- `Esc` → exit player
+
+### Optional inline album art
+
+Mercury supports inline album art as a progressive enhancement (text UI remains the default).
+
+- Enable with: `MERCURY_SPOTIFY_ART=1`
+- Currently rendered only in local iTerm sessions
+- Automatically falls back to text-only view in SSH/mobile/light terminals
+
## Managing Devices
Spotify plays on **your devices** — phone, desktop, TV, speaker. Mercury never plays audio locally. Before playing, Mercury checks what devices are available:
@@ -193,4 +211,4 @@ Your access and refresh tokens are also stored locally. Mercury never sends them
| "No active device" | Open Spotify on your phone/computer, play any song, then try again. |
| Browser doesn't open for auth | Use the manual code flow: `/spotify auth` → choose "Paste code" |
| Token expired after long idle | Run `/spotify auth` to get fresh tokens |
-| Account name not showing | Run `/spotify` and Mercury will fetch it live from Spotify's API |
\ No newline at end of file
+| Account name not showing | Run `/spotify` and Mercury will fetch it live from Spotify's API |
diff --git a/website/docs/integrations/sub-agents.mdx b/website/docs/integrations/sub-agents.mdx
index d392cad6..f0a39fb3 100644
--- a/website/docs/integrations/sub-agents.mdx
+++ b/website/docs/integrations/sub-agents.mdx
@@ -50,6 +50,10 @@ Mercury: I've delegated both tasks to parallel agents. Agent a1 is building the
| Command | Description |
|---------|-------------|
| `/agents` | List all sub-agents (running and completed) |
+| `/code agent <task>` | Delegate a coding task to a sub-agent immediately |
+| `/bg: <task>` | Run a natural-language sub-agent task in background |
+| `/bg current` | Move current in-flight task to a background sub-agent |
+| `/bg list` | List shell + sub-agent background tasks |
| `/halt` | Emergency: halt all sub-agents and clear the task queue |
| `/stop` | Full reset: halt agents, clear queue, release locks, clear task board |
@@ -134,6 +138,8 @@ If you send `/agents`, you'll see the full status:
⏳ a2: Write integration tests — pending
```
+Background-tracked agent tasks also appear in `/bg list` so shell jobs and delegated coding work share one progress surface.
+
## Configuration
Sub-agents are configured in `~/.mercury/mercury.yaml`:
@@ -167,4 +173,4 @@ Sub-agents pair well with Mercury's programming mode for code tasks:
## Programming Mode + Sub-Agents
-When `/code plan` is active, Mercury will analyze a task and present a plan. If the plan involves parallel work, Mercury can delegate parts to sub-agents during `/code execute`. The `ask_user` tool lets Mercury present choices at decision points — on CLI this is an arrow-key menu, on Telegram it's inline buttons.
\ No newline at end of file
+When `/code plan` is active, Mercury will analyze a task and present a plan. If the plan involves parallel work, Mercury can delegate parts to sub-agents during `/code execute`. The `ask_user` tool lets Mercury present choices at decision points — on CLI this is an arrow-key menu, on Telegram it's inline buttons.