WebChat - Transform CLI into a Conversation

WebChat makes any agent CLI available through a chat-style interface that users can reach from their browser.

What WebChat Delivers

💬

Conversational UI

Stream CLI input/output through a WhatsApp-inspired interface with bubbles, timestamps, and typing indicators.

🔐

Token Security

Each session is gated by an access token that lives in .ploinky/.secrets. Share the URL to grant access.

🛠️

Agent Ready

When a static workspace agent is configured, WebChat automatically connects to that agent’s manifest cli command.

Access & Tokens

Use ploinky webchat to print the current access URL or pass --rotate to mint a fresh token when needed.

ploinky webchat          # ensure token and show access URL
ploinky webchat --rotate # regenerate the token
Access URL format: http://127.0.0.1:8080/webchat?token=<WEBCHAT_TOKEN>

The token is stored as WEBCHAT_TOKEN in .ploinky/.secrets. Removing the entry or using --rotate forces a regeneration.

How Commands Are Chosen

WebChat derives its runtime command from the static workspace agent:

  1. Static agent – Configure one with ploinky start <agent> <port>. The router records the agent’s manifest path.
  2. Manifest CLI – When the agent’s manifest.json defines a cli command, WebChat runs it inside the agent container.
  3. No CLI? – Sessions still open, but the chat will display a notice that no command is bound.

This flow depends entirely on the static workspace agent: keep its manifest updated to control which CLI the chat session runs.

Session Experience

Message Rendering

  • ✅ Automatic timestamps for each exchange
  • ✅ Rich markdown rendering (tables, code blocks, lists)
  • ✅ Long output folding with “Show more” expansion
  • ✅ Side panel to inspect full message history

Input Controls

  • ✅ Auto-resizing composer with keyboard shortcuts (Enter to send, Shift+Enter for new line)
  • ✅ Light/Dark/Explorer/Obsidian Dark theme selector with persistent preference (Explorer loads by default; switch via Settings → Appearance)
  • ✅ Optional speech-to-text and text-to-speech integrations (see cli/server/webchat/strategies)

Security Practices

  • Rotate tokens regularly with ploinky webchat --rotate.
  • Prefer sharing short-lived tokens and revoke access by rotating after a session concludes.
  • Remember that tokens live in .ploinky/.secrets; secure that directory if you back it up or sync it.

Troubleshooting

  • Blank session? Verify the static agent has a cli command in its manifest.
  • 401 errors? Run ploinky webchat again to confirm the token and URL.
  • Need a different command? Update the agent manifest and restart the workspace so WebChat picks up the change.