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.mdindex 94d9d86a..e5402387 100644--- a/README.md+++ b/README.md@@ -45,6 +45,7 @@ To reconfigure later (change keys, name, settings):```bashmercury 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 AccessMercury uses an **organization access model** with admins and members.diff --git a/src/index.ts b/src/index.tsindex 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 @@ programprogram.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.tsindex 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.mdxindex 089e5ad3..7144bc4a 100644--- a/website/docs/cli-commands/doctor.mdx+++ b/website/docs/cli-commands/doctor.mdx@@ -12,4 +12,22 @@ title: Doctor (Reconfigure)```bashmercury 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.mdxindex 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 accessTelegram 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.mdxindex 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 tEvery 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 DevicesSpotify 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.mdxindex 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.+## ConfigurationSub-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.