agentp 0.9.0 → 0.10.0

package/AGENTS.md

@@ -86,6 +86,8 @@ These endpoints are consumed but not documented elsewhere in the repo:
 - Messages for the active server are delivered immediately; others are queued per-server.
 - Debounced Telegram notification (configurable via `TGAGENTP_DEBOUNCE_MS`, default 5000ms).
 - Queued messages are flushed on `/servers switch`.
+- Gateway response includes `{ buffered: [...] }` — recorded conversation messages (see `/record` command) flushed on each POST.
+- agentp `--qa` prepends the buffered context to stdout; `--flush` bypasses prepending but still triggers the flush.
 
 ## OpenCode tmux session model (ocmux)
 
@@ -103,7 +105,7 @@ These endpoints are consumed but not documented elsewhere in the repo:
 |---|---|---|
 | `npm link` | local dev install |
 | `npm install -g .` | alternative local install |
-| `agentp [--qa] [--tg|--no-tg] [port]` | pipe stdin → opencode session, stream answer to stdout (uses session API); `--tg` forwards answer to Telegram |
+| `agentp [--qa] [--tg|--no-tg] [--flush] [--getLast n] [port]` | pipe stdin → opencode session, stream answer to stdout (uses session API); `--tg` forwards answer to Telegram; `--flush` clears recorded buffer; `--getLast n` retrieves last n answers |
 | `tgagentp [port]` | bridge Telegram bot ↔ opencode TUI (needs `TELEGRAM_BOT_TOKEN`) |
 | `tgagentp --dev` | enable `/shutdown` command for remote restart |
 | `ocmux serve [--print-logs] [dir]` | start opencode serve in a tmux window (primary verb) |
@@ -116,7 +118,7 @@ These endpoints are consumed but not documented elsewhere in the repo:
 
 ### Pending
 
-- `agentp --getLast n` — retrieve last n answers from session history
+*(none)*
 
 ### In Progress
 
@@ -124,6 +126,9 @@ These endpoints are consumed but not documented elsewhere in the repo:
 
 ### Done
 
+- `/queue` command: queue messages when server is busy, auto-sent after current task finishes preserves replyTo chain — 0.10.0
+- `agentp --getLast n` — retrieve last n answers from session history — 0.10.0
+- `/record` command with ring buffer (100 msgs / 100KB), gateway returns `{ buffered }`, agentp `--qa` prepends recorded context, `--flush` flushes without prepending — 0.10.0
 - agentp `--qa` full context forwarding to Telegram (rulers, prompt, answer) — 0.9.0
 - agentp resilience: 5s HTTP timeout, pre-send gate check, post-send warning (not hard error) for `--tg`; auto mode silently degrades — 0.9.0
 - tgagentp: `lockedChatId` set at startup to fix race condition with agentp gateway — 0.9.0

package/CHANGELOG.md

@@ -2,11 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [0.10.0] - 2026-06-04
 
-- Rename package and CLI command from `aprompt` to `agentp`.
-- Extract shared OpenCode client logic into `lib/opencode.js`.
-- Add `tgagentp` — bridge a Telegram bot chat with an OpenCode TUI session.
+- `/queue` command: queue messages when server is busy, auto-sent after current task finishes, preserves replyTo chain.
+- `/record` command with ring buffer (100 msgs / 100KB), `/record stop` to clear; gateway returns `{ buffered }` JSON.
+- agentp `--flush`: flush tgagentp's recorded buffer without prepending to stdout.
+- agentp `--getLast n`: retrieve last n assistant answers from session history.
+- agentp `--qa` prepends recorded Telegram context (with rulers) to stdout.
+- `getSession()` in lib/opencode: `GET /session/:id` with fallback to session list.
+- `makeRequest` optional timeout parameter (used only for getSession; all other calls wait indefinitely).
+- Minimum 3-backtick code fence for reply quoting.
+
+## [0.9.0] - 2026-06-04
+
+- agentp `--tg`/`--no-tg` flags: gateway forwards answer to Telegram; auto mode silently degrades.
+- Agentp resilience: 5s HTTP timeout, pre-send gate check, post-send warning.
+- Full `--qa` output (rulers + prompt + answer) forwarded to Telegram.
+- Rulers changed from `—` to `─`, shortened to 17 chars.
 
 ## [0.8.0] - 2026-06-03
 

package/README.md

@@ -55,10 +55,13 @@ Options:
 - `--qa`: print the original prompt and answer with labels (useful when used as a filter)
 - `--tg`: forward the answer to Telegram via tgagentp gateway (error if unreachable)
 - `--no-tg`: do not forward to Telegram
+- `--flush`: flush tgagentp's recorded buffer without prepending it to output
+- `--getLast <n>`: retrieve last n assistant answers from session history
 - `--version`: show version
 - `--help`: show help message
 
-By default, `--qa` implies `--tg`; standalone mode implies `--no-tg`.
+By default, `--qa` auto-detects tgagentp (silently degrades if unavailable); standalone mode implies `--no-tg`.
+With `--tg`, errors if tgagentp is unavailable.
 
 Arguments:
 
@@ -124,6 +127,25 @@ From Vim/Neovim, forward the answer to your Telegram:
 (Works as long as `tgagentp` is running. The answer appears both in the editor
 and in your Telegram chat.)
 
+From Vim/Neovim, flush the recorded buffer without prepending context:
+
+```vim
+:'<,'>!agentp --qa --flush
+```
+
+Useful when you've finished a conversation thread and want to reset the recorded
+context for a new topic.
+
+Retrieve the last 3 assistant answers from session history:
+
+```bash
+agentp --getLast 3
+```
+
+Useful to grab recent answers without sending a new prompt.
+
+## ocmux
+
 ## ocmux
 
 Manage OpenCode server + TUI in tmux for project directories.
@@ -174,6 +196,10 @@ Notes:
 5. With `--tg` (or by default when `--qa` is given), forwards the answer to Telegram
    via the agentp gateway. The answer appears in your Telegram chat as if tgagentp
    itself had processed the request.
+6. If tgagentp's [/record](#tgagentp) feature was active, the gateway response includes
+   the recorded conversation buffer. In `--qa` mode, agentp prepends this buffer (with
+   rulers) to its stdout so OpenCode receives the full Telegram context. Use `--flush`
+   to clear the buffer without prepending.
 
 The session API ensures the request is processed even when no TUI is attached, and returns the full answer in a single HTTP response.
 
@@ -201,7 +227,7 @@ Non-text Telegram updates (photos, stickers, etc.) are silently ignored.
 
 | Command | Action |
 |---|---|
-| `/help [topic]` | Show general help or help for a topic (`servers`, `sessions`, `agents`, `models`, `allow`, `think`) |
+| `/help [topic]` | Show general help or help for a topic (`servers`, `sessions`, `agents`, `models`, `allow`, `think`, `record`, `queue`) |
 | `/servers` | List all running ocmux-served projects with URL + status (✅ idle / ⏳ busy) |
 | `/servers switch <name>` | Switch active server; matches by full path, basename, or substring |
 | `/sessions` | List recent sessions for the current server (max 50, with date headings) |
@@ -212,6 +238,8 @@ Non-text Telegram updates (photos, stickers, etc.) are silently ignored.
 | `/status` | Show current server path, URL, busy status, and active session |
 | `/cancel` | Cancel the current AI response for the active server |
 | `/think [on\|off\|switch]` | Toggle forwarding of model thinking messages to the chat |
+| `/record [stop]` | Toggle recording of Telegram conversation for agentp context; `/record stop` clears and stops |
+| `/queue <message>` | Queue a message when the server is busy; auto-sent when current task finishes |
 | `/allow` | Approve a permission request once |
 | `/reject` | Deny a permission request |
 | `/always` | Approve and remember for the session |
@@ -249,6 +277,7 @@ tgagentp starts a tiny HTTP server on `127.0.0.1` that accepts `POST /send` requ
 - Messages for the active server are delivered immediately.
 - Messages for non-active servers are queued and delivered on `/servers switch`.
 - Debounced Telegram notification on queue (configurable via `TGAGENTP_DEBOUNCE_MS`).
+- When [/record](#tgagentp) is active, the gateway response includes the recorded conversation buffer. `agentp --qa` prepends this buffer (with rulers) to its stdout so the full Telegram context is available to OpenCode. Use `agentp --qa --flush` to flush the buffer without prepending.
 
 ### Logging
 

package/bin/agentp

@@ -8,6 +8,7 @@ const {
   sendToSession,
   listSessions,
   createSession,
+  getSession,
 } = require('../lib/opencode');
 
 const TGAGENTP_PORT_FILE = '/tmp/tgagentp-port';
@@ -35,8 +36,16 @@ function notifyAgentpGateway(port, server, text) {
       let data = '';
       res.on('data', (chunk) => { data += chunk; });
       res.on('end', () => {
-        if (res.statusCode === 200) resolve();
-        else reject(new Error(`status ${res.statusCode}: ${data}`));
+        if (res.statusCode === 200) {
+          try {
+            const result = JSON.parse(data);
+            resolve(result.buffered || []);
+          } catch {
+            resolve([]);
+          }
+        } else {
+          reject(new Error(`status ${res.statusCode}: ${data}`));
+        }
       });
     });
     req.setTimeout(5000, () => {
@@ -66,6 +75,7 @@ const FINAL_ROW = '    —————————————————\n';
 async function main() {
   let serverBase = 'http://localhost:4096';
   let qaMode = false;
+  let flushMode = false;
   // tgMode: false = disabled, 'auto' = auto-detect, true = explicit --tg
   let tgMode = null;
 
@@ -84,6 +94,8 @@ async function main() {
       console.error('  --qa       Print the original prompt and answer with labels (useful as a filter)');
       console.error('  --tg       Forward the answer to Telegram via agentp gateway (error if unavailable)');
       console.error('  --no-tg    Do not forward to Telegram');
+      console.error('  --flush    Flush tgagentp\'s recorded buffer without prepending it to output');
+      console.error('  --getLast  Retrieve last N assistant answers from session history');
       console.error('  --help     Show this help message');
       console.error('');
       console.error('By default, --qa auto-detects tgagentp; standalone mode implies --no-tg.');
@@ -100,9 +112,65 @@ async function main() {
       console.error('  cat prompt.txt | agentp 4096');
       console.error('  # Vim/Neovim filter, preserving prompt + answer:');
       console.error("  :'<,'>!agentp --qa");
+      console.error('  # Retrieve last 3 assistant answers:');
+      console.error('  agentp --getLast 3');
+      console.error('  agentp --getLast 1 4096');
       process.exit(0);
     } else if (args[i] === '--qa') {
       qaMode = true;
+    } else if (args[i] === '--flush') {
+      flushMode = true;
+    } else if (args[i] === '--getLast') {
+      i++;
+      const nStr = args[i];
+      if (!nStr || !/^\d+$/.test(nStr)) {
+        console.error('Error: --getLast requires a number (e.g. --getLast 5)');
+        process.exit(1);
+      }
+      const n = parseInt(nStr, 10);
+      try {
+        const sessions = await listSessions(serverBase);
+        if (!sessions || sessions.length === 0) {
+          console.error('No sessions found.');
+          process.exit(1);
+        }
+        const sorted = sessions
+          .filter(s => s.time && s.time.updated)
+          .sort((a, b) => b.time.updated - a.time.updated);
+        // Try to extract messages; getSession may return data with
+        // messages, or the sessions list may already contain them
+        let rawMessages = [];
+        try {
+          const session = await getSession(serverBase, sorted[0].id);
+          rawMessages = session.messages || session.history || session.conversation || [];
+        } catch {
+          // If the dedicated endpoint fails, the list data may have messages
+          rawMessages = sorted[0].messages || sorted[0].history || sorted[0].conversation || [];
+        }
+        if (rawMessages.length === 0) {
+          console.error('No message history available for the most recent session.');
+          console.error('The OpenCode server may not expose message history via the HTTP API.');
+          process.exit(1);
+        }
+        const assistantTexts = rawMessages
+          .filter(m => m.role === 'assistant')
+          .map(m => {
+            if (m.parts) return m.parts.filter(p => p.type === 'text').map(p => p.text).join('');
+            return m.content || m.text || '';
+          })
+          .filter(t => t.trim());
+        if (assistantTexts.length === 0) {
+          console.error('No assistant answers found in session history.');
+          process.exit(1);
+        }
+        const lastN = assistantTexts.slice(-n);
+        process.stdout.write(lastN.join('\n'));
+        if (lastN.length > 0 && !lastN[lastN.length - 1].endsWith('\n')) process.stdout.write('\n');
+      } catch (err) {
+        console.error('Error retrieving session history:', err.message);
+        process.exit(1);
+      }
+      return;
     } else if (args[i] === '--tg') {
       tgMode = true;
     } else if (args[i] === '--no-tg') {
@@ -172,28 +240,39 @@ async function main() {
     process.exit(1);
   }
 
-  // Build full --qa output and send to stdout
-  let tgText = answer;
+  // Build the message to send to Telegram (QA pair with rulers)
+  let tgMessage = answer;
   if (qaMode) {
-    tgText = HUMAN_ROW + promptText + AGENT_ROW + answer;
-    if (!answer.endsWith('\n')) tgText += '\n';
-    tgText += FINAL_ROW;
-    process.stdout.write(tgText);
-  } else {
-    process.stdout.write(answer);
-    if (!answer.endsWith('\n')) process.stdout.write('\n');
+    tgMessage = HUMAN_ROW + promptText + AGENT_ROW + answer;
+    if (!answer.endsWith('\n')) tgMessage += '\n';
+    tgMessage += FINAL_ROW;
   }
 
-  // Post-send: notify tgagentp if we have a port
+  // Post-send: notify tgagentp, get recorded context back
+  let buffered = [];
   let tgError = null;
   if (tgPort) {
     try {
-      await notifyAgentpGateway(tgPort, serverBase, tgText);
+      buffered = await notifyAgentpGateway(tgPort, serverBase, tgMessage);
     } catch (err) {
       tgError = err;
     }
   }
 
+  // Build stdout output (prepend recorded context if any, unless --flush)
+  if (qaMode) {
+    if (!flushMode && buffered.length > 0) {
+      for (const msg of buffered) {
+        const row = msg.role === 'user' ? HUMAN_ROW : AGENT_ROW;
+        process.stdout.write(row + msg.text + '\n');
+      }
+    }
+    process.stdout.write(tgMessage);
+  } else {
+    process.stdout.write(tgMessage);
+    if (!tgMessage.endsWith('\n')) process.stdout.write('\n');
+  }
+
   // Warnings at the end (stderr)
   if (tgError && tgMode === true) {
     process.stderr.write('\n');

package/bin/ocmux

@@ -192,7 +192,7 @@ function printHelp() {
   console.error('          --git  Use the nearest parent with a .git entry (file or dir).');
   console.error('          --GIT  Use the nearest parent with a .git directory only.');
   console.error('          Refuses to create above an existing .ocmux.json found while searching.');
-  console.error(          '          --print-logs  Pass --print-logs to opencode serve (prints server logs to stderr).');
+  console.error('          --print-logs  Pass --print-logs to opencode serve (prints server logs to stderr).');
   console.error('  kill    Kill the server found upward from <directory>.');
   console.error('          Removes its tmux window and state file.');
   console.error('  list    List all running servers with their directories and URLs.');

package/bin/tgagentp

@@ -49,6 +49,32 @@ function flushAgentpQueue(server, token, chatId) {
     .catch(() => {});
 }
 
+// ---------------------------------------------------------------------------
+// /record — ring buffer for Telegram conversation context
+// ---------------------------------------------------------------------------
+
+const MAX_RECORDED_MSGS = 100;
+const MAX_RECORDED_BYTES = 100 * 1024;
+
+const recorder = { active: false, messages: [], bytes: 0 };
+
+function bufferMessage(role, text) {
+  if (!recorder.active) return;
+  recorder.messages.push({ role, text });
+  recorder.bytes += Buffer.byteLength(text, 'utf8');
+  while (recorder.messages.length > MAX_RECORDED_MSGS || recorder.bytes > MAX_RECORDED_BYTES) {
+    const oldest = recorder.messages.shift();
+    recorder.bytes -= Buffer.byteLength(oldest.text, 'utf8');
+  }
+}
+
+function flushRecorded() {
+  if (!recorder.active) return [];
+  const msgs = recorder.messages.splice(0);
+  recorder.bytes = 0;
+  return msgs;
+}
+
 // ---------------------------------------------------------------------------
 // Telegram Bot API helpers
 // ---------------------------------------------------------------------------
@@ -226,7 +252,7 @@ function quoteReply(msg) {
     if (rm.text[i] === '`') { cur++; maxBackticks = Math.max(maxBackticks, cur); }
     else cur = 0;
   }
-  const fence = '`'.repeat(maxBackticks + 1);
+  const fence = '`'.repeat(Math.max(3, maxBackticks + 1));
   return `In response to ${replyFrom} (${senderType}):\n\n${fence}\n${rm.text}\n${fence}\n\n`;
 }
 
@@ -307,8 +333,28 @@ async function cmdHelp(token, chatId, args) {
         'Can also be enabled at startup with `--think` flag.');
       return;
     }
+    if (topic === 'queue') {
+      await sendLongMessage(token, chatId,
+        '`/queue <message>` ─ queue a message when the server is busy\n\n' +
+        'When the server is processing a previous message, queuing allows you to\n' +
+        'continue working without waiting. Once the current task finishes, the next\n' +
+        'queued message is automatically sent and the answer will reply to the\n' +
+        'original queued message.');
+      return;
+    }
+    if (topic === 'record') {
+      await sendLongMessage(token, chatId,
+        '`/record` ─ toggle recording of messages for agentp context\n' +
+        '`/record stop` ─ stop recording and clear buffer\n\n' +
+        'When recording is active, all user and assistant messages are buffered in memory\n' +
+        '(max 100 messages / 100KB). The next `agentp` invocation retrieves the buffered\n' +
+        'conversation and prepends it to its `--qa` stdout output, so OpenCode can\n' +
+        'see the full conversation context.\n\n' +
+        'Buffered messages are NOT sent back to Telegram (they are already there).');
+      return;
+    }
     await sendLongMessage(token, chatId,
-      'Unknown topic. Try `/help servers`, `/help sessions`, `/help session`, `/help agents`, `/help models`, `/help allow`, `/help think`, or just `/help`.');
+      'Unknown topic. Try `/help servers`, `/help sessions`, `/help session`, `/help agents`, `/help models`, `/help allow`, `/help think`, `/help record`, `/help queue`, or just `/help`.');
     return;
   }
   await sendLongMessage(token, chatId,
@@ -327,6 +373,8 @@ async function cmdHelp(token, chatId, args) {
     '`/agents switch <name>` ─ switch active agent\n' +
     '`/models` ─ list providers and models\n' +
     '`/think` ─ toggle thinking message forwarding\n' +
+    '`/record` ─ record Telegram conversation for agentp context\n' +
+    '`/queue <message>` ─ queue a message when server is busy\n' +
     '`/allow` / `/reject` / `/always` ─ respond to permission requests\n' +
     '`/shutdown` ─ stop tgagentp (only with `--dev` flag)\n\n' +
     'Everything else is forwarded to the active server as `[Telegram] <text>`.');
@@ -740,10 +788,13 @@ function startAgentpGateway(token, chatIdResolver, serverBaseResolver) {
               res.end('Bad Request: text and server are required');
               return;
             }
-            res.writeHead(200);
-            res.end('OK');
-
             const chatId = chatIdResolver();
+
+            // Return recorded conversation buffer before forwarding
+            const buffered = flushRecorded();
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ buffered }));
+
             if (!chatId) return;
             const activeUrl = normalizeUrl(serverBaseResolver());
             const targetUrl = normalizeUrl(server);
@@ -854,6 +905,39 @@ async function cmdThink(token, chatId, args, setServer, setActiveSession, server
   }
 }
 
+async function cmdQueue(token, chatId, args, _, __, serverBase, replyTo) {
+  const st = getState(serverBase);
+  if (!st.busy) {
+    await sendLongMessage(token, chatId, 'Server is not busy. No need to queue — send your message directly.');
+    return;
+  }
+  const text = args.join(' ').trim();
+  if (!text) {
+    await sendLongMessage(token, chatId, 'Usage: `/queue <message>` — queue a message for when the server is idle.');
+    return;
+  }
+  if (!st.messageQueue) st.messageQueue = [];
+  st.messageQueue.push({ text, replyTo });
+  await sendLongMessage(token, chatId, `📥 Queued. ${st.messageQueue.length} message(s) in queue. Will be sent when the current task finishes.`);
+}
+
+async function cmdRecord(token, chatId, args) {
+  if (args.length > 0 && args[0].toLowerCase() === 'stop') {
+    recorder.active = false;
+    recorder.messages = [];
+    recorder.bytes = 0;
+    await sendLongMessage(token, chatId, '⏹ Recording stopped. Buffer cleared.');
+    return;
+  }
+  recorder.active = !recorder.active;
+  if (!recorder.active) {
+    recorder.messages = [];
+    recorder.bytes = 0;
+  }
+  await sendLongMessage(token, chatId,
+    recorder.active ? '🔴 Recording started. Messages will be cached for agentp.' : '⏹ Recording stopped. Buffer cleared.');
+}
+
 const COMMANDS = {
   'help': cmdHelp,
   'servers': cmdServers,
@@ -862,6 +946,8 @@ const COMMANDS = {
   'agents': cmdAgents,
   'models': cmdModels,
   'think': cmdThink,
+  'record': cmdRecord,
+  'queue': cmdQueue,
   'allow': cmdAllow,
   'reject': cmdReject,
   'always': cmdAlways,
@@ -873,7 +959,7 @@ const COMMANDS = {
 
 const serverState = {};
 function getState(url) {
-  return serverState[url] = serverState[url] || { busy: false, pendingResponse: null, activeSessionId: null, activeSessionName: null, activeAgentName: null, taskId: 0, pendingPermission: null, thinkingEnabled: false };
+  return serverState[url] = serverState[url] || { busy: false, pendingResponse: null, activeSessionId: null, activeSessionName: null, activeAgentName: null, taskId: 0, pendingPermission: null, thinkingEnabled: false, messageQueue: [] };
 }
 
 function sessionLabel(st) {
@@ -1113,11 +1199,14 @@ async function main() {
       st.pendingPermission = null;
       if (url === serverBase) {
         if (answer && answer.trim()) {
-          await sendLongMessage(token, chatId, answer.trim(), replyTo);
+          const trimmed = answer.trim();
+          await sendLongMessage(token, chatId, trimmed, replyTo);
+          bufferMessage('assistant', trimmed);
         }
       } else {
         getState(url).pendingResponse = answer;
         await sendLongMessage(token, chatId, `✅ Server \`${url}\` finished processing. Switch back to see the response.`, replyTo);
+        if (answer && answer.trim()) bufferMessage('assistant', answer.trim());
       }
     } catch (err) {
       // Clean up SSE listener if it's still active
@@ -1137,6 +1226,21 @@ async function main() {
       if (st._sessionReq === sessionCancelRef) st._sessionReq = null;
       if (!isCancelled()) {
         getState(url).busy = false;
+        // Drain message queue for this server
+        const q = st.messageQueue || [];
+        st.messageQueue = [];
+        if (q.length > 0) {
+          const next = q[0];
+          // Re-queue remaining items (if any) for the next round
+          st.messageQueue = q.slice(1);
+          const nextText = next.text;
+          const nextReplyTo = next.replyTo;
+          // Mark busy again and process
+          getState(url).busy = true;
+          const nextTaskId = ++st.taskId;
+          log.debug(`  → processing queued message (task ${nextTaskId})`);
+          processMessageAsync(chatId, nextText, url, !!st.activeSessionId, st.activeSessionId, nextTaskId, nextReplyTo);
+        }
       }
     }
   }
@@ -1285,15 +1389,18 @@ async function main() {
           }
         } else {
           await sendLongMessage(token, chatId,
-            `Unknown command: /${cmd}\n\nAvailable commands: /help, /status, /servers, /sessions, /agents, /models`);
+            `Unknown command: /${cmd}\n\nAvailable commands: /help, /status, /servers, /sessions, /agents, /models, /think, /record, /queue`);
         }
         continue;
       }
 
+      // Buffer user messages for /record
+      bufferMessage('user', replyContext + text);
+
       // Non-command message ─ process in background
       const st = getState(serverBase);
       if (st.busy) {
-        await sendLongMessage(token, chatId, '⏳ Server is busy processing a previous message. Please wait for it to finish, or use /cancel to cancel it.');
+        await sendLongMessage(token, chatId, '⏳ Server is busy. Use `/cancel` to cancel or `/queue <message>` to queue your message.');
         continue;
       }
       st.busy = true;

package/devto-article.md

@@ -0,0 +1,121 @@
+# Agentp: Turn OpenCode Into a Headless AI Engine for Your Editor, Terminal, and Telegram
+
+OpenCode is great, but its TUI locks you in. You type in one window, watch it stream, and that's it. What if you could:
+
+- Pipe a prompt straight from Vim and replace your selection with the answer?
+- Queue messages from Telegram while it's busy and get replies threaded?
+- Keep a permanent tmux server per project and switch between them?
+- Pull the last N answers from session history without sending a new prompt?
+- Record your Telegram conversation and inject it as context into your next `agentp` call?
+
+That's what **agentp** — a set of three zero-dependency Node.js CLI tools — does.
+
+---
+
+## The Three Tools
+
+### `agentp` — The Pipe
+
+Stdin in, answer out. That's the core loop.
+
+```bash
+printf "Summarize this file" | agentp
+cat prompt.txt | agentp 4096
+```
+
+From Vim/Neovim:
+
+```vim
+:'<,'>!agentp --qa
+```
+
+This replaces your visual selection with the answer. `--qa` preserves the prompt + answer with labels, so you keep the full context.
+
+### `ocmux` — The Project Manager
+
+Each project gets its own tmux window with a dedicated `opencode serve` + TUI pane. Auto-restarts dead panes, pins window names, stores state in `.ocmux.json` (discovered upward like `.git`).
+
+```bash
+ocmux serve ~/projects/myapp   # create
+ocmux list                      # list all
+ocmux ~/projects/myapp          # switch
+ocmux kill ~/projects/myapp     # remove
+```
+
+### `tgagentp` — The Telegram Bridge
+
+A Telegram bot that routes messages to your OpenCode servers. Multi-server aware, slash-commands for everything.
+
+**Slash commands:**
+
+| Command | What it does |
+|---|---|
+| `/servers` | List/switch between ocmux projects |
+| `/sessions` | List/switch/create/rename sessions |
+| `/agents` | List/switch active agent |
+| `/models` | List providers and models |
+| `/queue <msg>` | Queue message when busy — auto-sent after current task finishes (replies chain!) |
+| `/record` | Record conversation for `agentp` context injection |
+| `/think` | Toggle real-time thinking message forwarding |
+| `/cancel` | Abort the running prompt |
+
+---
+
+## The Agentp Gateway
+
+The killer integration: `agentp` and `tgagentp` talk to each other through a tiny HTTP gateway.
+
+- **`agentp --tg`** forwards the answer to your Telegram chat after every pipe.
+- **`agentp --qa`** auto-detects tgagentp and sends the full QA pair (rulers + prompt + answer).
+- **`/record`** buffers the Telegram conversation. On the next `agentp` call, the gateway returns the buffer, and `--qa` prepends it to stdout with rulers — so OpenCode sees the full Telegram thread as context.
+- **`agentp --flush`** clears the buffer without prepending.
+- **`agentp --getLast 5`** retrieves the last 5 assistant answers from session history.
+
+```vim
+:'<,'>!agentp --qa --tg          " answer in editor + Telegram
+:'<,'>!agentp --qa --flush       " flush recorded buffer
+```
+
+All of this with **zero npm dependencies** — just Node.js 18+ stdlib.
+
+---
+
+## Why This Setup Works
+
+1. **Session API, not TUI hooks** — messages go through `POST /session/:id/message`, which returns synchronously. No fragile TUI scraping.
+2. **Per-project tmux isolation** — each project gets its own `opencode serve` process. Switch with a single command.
+3. **Graceful degradation** — `--tg` in auto mode silently skips Telegram if tgagentp isn't running. Explicit `--tg` errors pre-send, warns post-send.
+4. **10s HTTP timeout on every request** — nothing ever hangs.
+5. **Async processing** — tgagentp never blocks the polling loop. Commands stay responsive even while a prompt runs.
+
+---
+
+## Quick Start
+
+```bash
+npm install -g agentp
+
+# Start a project server
+ocmux serve ~/projects/myapp
+
+# Pipe a prompt
+printf "Explain this codebase" | agentp
+
+# With Telegram (set up a bot with @BotFather first)
+export TELEGRAM_BOT_TOKEN="your-token"
+tgagentp
+```
+
+If your OpenCode server is password-protected, set `OPENCODE_SERVER_PASSWORD`.
+
+---
+
+## Links
+
+- **GitHub:** [github.com/bitifet/agentp](https://github.com/bitifet/agentp)
+- **npm:** [npmjs.com/package/agentp](https://www.npmjs.com/package/agentp)
+- **OpenCode:** [github.com/anthropics/claude-code](https://github.com/anthropics/claude-code)
+
+---
+
+*Feedback? Issues? PRs welcome.*