ticlawk 0.1.15-dev.6 → 0.1.16-dev.1

package/README.md

@@ -2,125 +2,45 @@
 
 [![npm version](https://img.shields.io/npm/v/ticlawk)](https://www.npmjs.com/package/ticlawk)
 
-**Connect any agent harness to any mobile client.**
+**The local connector that lets the Ticlawk mobile app drive your agent harnesses.**
 
-*M agent harnesses × N mobile clients used to be M×N integrations. ticlawk makes it M+N.*
-
-You run the harness locally — Claude Code, Codex, OpenClaw, whatever you're
-testing this week. `ticlawk` is the layer that lets any of them talk
-through any mobile/web client you like to use (Telegram,
-[ticlawk](https://ticlawk.com), more to come). 
-
-<p align="center">
-  <img src="assets/ticlawk-concept.svg" alt="ticlawk connects any client to any agent" width="860">
-</p>
-
-Left side: any agent harness that runs on your machine.
-Middle: `ticlawk`.
-Right side: any mobile or web app you like to use to manage your agent.
+You run the agent harness on your machine — Claude Code, Codex, OpenClaw,
+opencode, or pi. `ticlawk` is the daemon that connects those local harnesses
+to the [Ticlawk mobile app](https://ticlawk.com) so you can chat with them
+from your phone.
 
 ---
 
-## Quickstart — Telegram in 5 minutes
+## Quickstart — 2 minutes
 
-This is the fastest way to see it work. You need a Telegram bot token from
-[@BotFather](https://t.me/BotFather) and a project directory on this machine
-where Claude Code can run.
+You need a project directory on this machine where Claude Code (or another
+supported runtime) can run, and the Ticlawk app installed on your phone.
 
 ```bash
 # 1. install
 curl -fsSL https://raw.githubusercontent.com/darthjaja6/ticlawk/main/install.sh | bash
 
-# 2. choose Telegram as the active adapter
-ticlawk config set adapter telegram
-
-# 3. store Telegram auth locally
-ticlawk auth telegram --bot-token <your-bot-token>
-
-# 4. restart the daemon so it starts polling the bot
-# Linux
-systemctl --user restart ticlawk
-
-# macOS
-launchctl kickstart -k gui/$(id -u)/ticlawk
-
-# 5. connect that bot to a Claude Code project
-ticlawk connect --adapter telegram --workdir /path/to/project
-
-# optional: if you want to resume an existing Claude Code session instead,
-# add --session-id <claude-session-id>
-
-# 6. say hi to your bot on Telegram — the first DM becomes the bot's only chat
-```
-
-`--workdir` is the important part. `ticlawk` binds the adapter to a local
-project directory and runtime. `--session-id` is optional: use it only when you
-want to resume an existing Claude Code or Codex conversation instead of letting
-the next message create a fresh session automatically.
-
-**Finding `<claude-session-id>`** — if you want to resume, use the filename
-(without `.jsonl`) of the transcript under `~/.claude/projects/**/`. Pick the
-one whose working directory matches the project you want the bot to work on.
-
-If `hello` in Telegram comes back as a reply from that Claude Code session,
-you're done. Everything below is for when you want ticlawk, Codex, OpenClaw,
-or more control.
-
-> ⚠️ **Single user, by design.** The Telegram bot binds to the **first** private
-> DM that messages it, and refuses everyone else. This is not a bug — it's the
-> security boundary. The bot can run shell commands and edit files in your
-> project; locking it to one chat keeps that capability where you intended.
-> Don't add the bot to groups, and don't share its token.
-
----
-
-## Using ticlawk instead of Telegram
-
-If you want the [ticlawk mobile app](https://ticlawk.com) instead, connect from
-the project directory and scan the QR code with ticlawk. `ticlawk` will
-detect local runtimes in that directory, and ticlawk will ask you which one to
-connect:
-
-```bash
+# 2. connect this machine to your Ticlawk account by scanning the QR code
 cd /path/to/project
 ticlawk connect
 ```
 
-Full walkthrough: [docs/clients/ticlawk.md](docs/clients/ticlawk.md).
-Telegram details: [docs/clients/telegram.md](docs/clients/telegram.md).
+`ticlawk connect` auto-detects every supported runtime in that project
+directory (Codex, Claude Code, opencode, pi) and lets you pick one inside the
+app once pairing completes. Run `ticlawk connect` again from a different
+directory when you want to bind a new project.
 
----
-
-## Using Codex, OpenClaw, or opencode instead of Claude Code
-
-Keep the same two-step adapter flow:
-
-1. `ticlawk auth <adapter> ...`
-2. `ticlawk connect --adapter <adapter> ...`
-
-Then swap the runtime locator with `--type`:
-
-```bash
-# Telegram + Codex
-ticlawk connect --adapter telegram --type codex --workdir /path/to/project
-
-# ticlawk + Codex, when you want to bypass mobile runtime selection
-ticlawk connect --adapter ticlawk --type codex --workdir /path/to/project
-
-# Telegram + OpenClaw
-ticlawk connect --adapter telegram --type openclaw --agent-id main
-
-# ticlawk + OpenClaw
-ticlawk connect --adapter ticlawk --type openclaw --agent-id main
+> ⚠️ **Single user, by design.** The connector binds to your Ticlawk account;
+> agents run with your local user's permissions and can edit files / run
+> commands inside the bound `--workdir`. Don't share your connector API key
+> and don't connect a workdir you wouldn't trust a shell to touch.
 
-# Telegram + opencode
-ticlawk connect --adapter telegram --type opencode --workdir /path/to/project
+---
 
-# ticlawk + opencode, when you want to bypass mobile runtime selection
-ticlawk connect --adapter ticlawk --type opencode --workdir /path/to/project
-```
+## Resuming an existing runtime session
 
-Runtime locators at a glance:
+By default each new chat creates a fresh runtime session. To resume an
+existing Claude Code or Codex transcript, point at it explicitly:
 
 | Runtime     | Required       | Optional resume handle | Where to find it                                              |
 |-------------|----------------|------------------------|---------------------------------------------------------------|
@@ -132,9 +52,6 @@ Runtime locators at a glance:
 [OpenClaw](https://github.com/openclaw/openclaw) is an open-source local-first
 agent runtime; skip this row if you don't use it.
 
-OpenClaw has built-in channels; use `ticlawk` only if you want a single
-chat surface across Claude Code, Codex, OpenClaw, and opencode.
-
 [opencode](https://opencode.ai) is provider-agnostic — it doesn't carry its own
 account system. Before connecting through `ticlawk`, install the CLI
 (`npm i -g opencode-ai`) and authenticate it once against the LLM provider
@@ -143,50 +60,25 @@ Google / OpenRouter / etc. and paste the corresponding API key). Model
 selection lives in opencode's own config (`opencode.json` in the project
 root, or user-level config) — `ticlawk` does not pass `--model`.
 
-`ticlawk` spawns opencode with `--dangerously-skip-permissions`
-(matching how Codex is wired), so chat messages can drive shell commands and
-file edits in the bound `--workdir` without further confirmation prompts.
-This is the same security boundary documented above; only connect a workdir
-you trust to a chat you control.
-
----
-
-## `auth` vs `connect`
-
-You only need to know this once:
-
-- **`auth`** — store adapter-specific setup input locally.
-  Telegram takes `--bot-token`. ticlawk uses QR pairing from `connect`.
-- **`connect`** — connect the selected adapter to a local runtime.
-  For ticlawk, `ticlawk connect` auto-detects local runtimes and
-  lets you pick in the mobile app. Use `--workdir` for Telegram or explicit
-  ticlawk runtime selection, optionally add `--session-id` to resume, or use
-  `--agent-id` for OpenClaw.
-
-`auth` is adapter-specific by subcommand shape:
-- `ticlawk auth telegram --bot-token ...`
-
-That keeps adapter auth flags scoped to the adapter without making users learn
-the `--` passthrough convention.
+`ticlawk` spawns opencode and codex with `--dangerously-skip-permissions`-style
+flags so chat messages can drive shell commands and file edits in the bound
+workdir without further confirmation prompts. Only connect a workdir you
+trust to a chat you control.
 
 ---
 
 ## Daily use
 
-After setup, the usual workflow is simple:
+After setup:
 
 - Keep `ticlawk` running as a user service. If Linux prints an
   `Action required` message during install or connect, run the command it
   shows so the daemon keeps running after logout and reboot.
-- Keep using the same Telegram chat or ticlawk channel. The adapter auth and
-  channel binding stay on disk until you change them.
-- If you want to have the work done just like tiktoking, run
-  `ticlawk connect ...` again with the new `--workdir`.
-- If you want to resume an existing Claude Code or Codex conversation, add
-  `--session-id`; otherwise the next message creates a fresh session.
-- If an OpenClaw agent changes, reconnect with the new `--agent-id`.
-- If replies stop because the local runtime session ended, run `connect` again
-  or reset the session from the client UI.
+- Bind to a new project: run `ticlawk connect` from the new directory.
+- Resume an existing transcript: add `--session-id` (Claude Code / Codex /
+  opencode) or `--agent-id` (OpenClaw) to the `connect` call.
+- If replies stop because the local runtime session ended, run `connect`
+  again or reset the session from the app.
 - `ticlawk health` is the first thing to check when something feels off.
 
 ---
@@ -197,16 +89,12 @@ After setup, the usual workflow is simple:
 ticlawk health
 ```
 
-- `ok: true` and the adapter-specific fields populated → you're good.
+- `ok: true` and `apiKey: true` → you're good.
 - Can't reach `127.0.0.1:8741` → the daemon isn't running. Start it with
   `systemctl --user restart ticlawk`,
   `launchctl kickstart -k gui/$(id -u)/ticlawk`, or `ticlawk start`.
-- Telegram shows `runtimeConnected: true` and `connectedChat: false` →
-  send the first DM to the bot to claim its only chat.
-- Telegram shows `botConfigured: false` → rerun
-  `ticlawk auth telegram --bot-token ...`, then restart the daemon.
-- ticlawk shows `apiKey: false` → rerun `ticlawk connect`
-  from the project directory and scan the QR code.
+- `apiKey: false` → rerun `ticlawk connect` from the project directory and
+  scan the QR code with the Ticlawk app.
 
 Logs:
 
@@ -253,9 +141,8 @@ ticlawk connect
 systemd linger is off, it prints the same `Action required` message shown by
 the installer.
 
-Update with `ticlawk update`. To remove the service and managed
-install files while keeping `~/.ticlawk` config, bindings, profiles, and
-logs:
+Update with `ticlawk update`. To remove the service and managed install
+files while keeping `~/.ticlawk` config, bindings, profiles, and logs:
 
 ```bash
 ticlawk uninstall
@@ -268,22 +155,19 @@ That removes:
 - `~/.config/systemd/user/ticlawk.service` (Linux)
 - `~/Library/LaunchAgents/ticlawk.plist` (macOS)
 
-`~/.ticlawk` is preserved. Use `npm uninstall -g ticlawk` to remove
-the npm package itself.
+`~/.ticlawk` is preserved. Use `npm uninstall -g ticlawk` to remove the npm
+package itself.
 
 ---
 
 ## Config
 
-Config lives in `~/.ticlawk/.config`. Most people only need to set
-`adapter`, then use `auth` for adapter-specific setup. The dotted
-credential keys below still exist for manual or advanced setups.
+Config lives in `~/.ticlawk/.config`. Most users never edit it directly —
+`ticlawk connect` writes the connector API key for you. The keys below exist
+for advanced/manual setups.
 
 ```bash
 ticlawk config                              # show current config
-ticlawk config set adapter telegram         # or: ticlawk
-ticlawk auth telegram --bot-token <t>
-ticlawk config set telegram.bot-token <t>   # advanced/manual override
 ticlawk config set ticlawk.connector-api-key <k> # advanced/manual override
 ticlawk config set ticlawk.connector-ws-url <url> # advanced/manual override
 ticlawk config set streaming off            # disable streaming output globally
@@ -293,13 +177,11 @@ ticlawk config set streaming.codex default  # clear the codex override; inherit
 
 Key mapping (for anyone editing the file directly):
 
-| Config key            | Env var              |
-|-----------------------|----------------------|
-| `adapter`             | `AF_ADAPTER`         |
-| `telegram.bot-token`  | `TELEGRAM_BOT_TOKEN` |
-| `ticlawk.connector-api-key` | `TICLAWK_CONNECTOR_API_KEY` |
-| `ticlawk.api-url`     | `TICLAWK_API_URL`    |
-| `ticlawk.connector-ws-url` | `TICLAWK_CONNECTOR_WS_URL` |
+| Config key                  | Env var                       |
+|-----------------------------|-------------------------------|
+| `ticlawk.connector-api-key` | `TICLAWK_CONNECTOR_API_KEY`   |
+| `ticlawk.api-url`           | `TICLAWK_API_URL`             |
+| `ticlawk.connector-ws-url`  | `TICLAWK_CONNECTOR_WS_URL`    |
 
 Streaming defaults to on. Full CLI reference: `ticlawk help`.
 
@@ -317,9 +199,9 @@ Usage:
   ticlawk start
   ticlawk health
   ticlawk config
-  ticlawk config get <adapter|streaming...|runtimes.claude_code.path|runtimes.codex.path|runtimes.opencode.path|runtimes.pi.path|telegram.bot-token|ticlawk.connector-api-key|ticlawk.api-url|ticlawk.connector-ws-url>
-  ticlawk config set <adapter|streaming...|runtimes.claude_code.path|runtimes.codex.path|runtimes.opencode.path|runtimes.pi.path|telegram.bot-token|ticlawk.connector-api-key|ticlawk.api-url|ticlawk.connector-ws-url> <value>
-  ticlawk auth <adapter> [adapter-auth-args...]
+  ticlawk config get <streaming...|runtimes.claude_code.path|runtimes.codex.path|runtimes.opencode.path|runtimes.pi.path|ticlawk.connector-api-key|ticlawk.api-url|ticlawk.connector-ws-url>
+  ticlawk config set <streaming...|runtimes.claude_code.path|runtimes.codex.path|runtimes.opencode.path|runtimes.pi.path|ticlawk.connector-api-key|ticlawk.api-url|ticlawk.connector-ws-url> <value>
+  ticlawk auth --code <6-digit-code> [--api-url <url>]
   ticlawk connect
   ticlawk profile list
   ticlawk profile current
@@ -330,31 +212,27 @@ Usage:
   ticlawk version
 
 Commands:
-  auth     store adapter-specific auth/setup input locally
-  connect  connect the selected adapter to a local runtime
+  auth     store the ticlawk app pairing code locally
+  connect  connect ticlawk to a local runtime
   profile  list or switch saved local identities
   install-daemon  install or refresh the background daemon
   update   update the npm package and refresh the daemon
   uninstall  remove service and managed install files, preserving ~/.ticlawk
 
 Config examples:
-  ticlawk config get adapter
-  ticlawk config set adapter telegram
-  ticlawk config set adapter ticlawk
   ticlawk config set streaming off                    # turn streaming off for all runtimes
   ticlawk config set streaming.codex default          # clear the codex-specific override and inherit the global streaming setting
   ticlawk config set runtimes.claude_code.path /path/to/claude_code # advanced/manual
   ticlawk config set runtimes.codex.path /path/to/codex # advanced/manual
   ticlawk config set runtimes.opencode.path /path/to/opencode # advanced/manual
   ticlawk config set runtimes.pi.path /path/to/pi # advanced/manual
-  ticlawk config set telegram.bot-token <bot-token>   # advanced/manual
   ticlawk config set ticlawk.connector-api-key <key>   # advanced/manual
   ticlawk config set ticlawk.api-url <api-url>        # advanced/manual
   ticlawk config set ticlawk.connector-ws-url <url>   # advanced/manual
 
 Examples:
   ticlawk connect
-  ticlawk auth telegram --bot-token <bot-token>
+  ticlawk auth --code <6-digit-code>
 ```
 <!-- usage:end -->
 
@@ -362,51 +240,44 @@ Examples:
 
 ## Security model
 
-This is the part to read before you set anything up.
-
-- **The bot can run code on your machine.** Whatever Claude Code / Codex /
-  OpenClaw can do in the bound `--workdir`, the chat client can ask it to do.
-  Treat the chat as you'd treat a shell.
-- **Single chat, single user.** The Telegram adapter binds to the first private
-  DM and rejects all others. The ticlawk adapter binds to one channel per
-  connect. Don't share bot tokens or connector credentials.
-- **Secrets stay local.** Bot tokens, ticlawk API keys, and binding metadata
-  live in `~/.ticlawk/.config` (mode `0600`) and never leave your
-  machine. The daemon listens on `127.0.0.1:8741` only — it does not bind to
-  any external interface.
-- **Token leak = remote shell.** If your Telegram bot token leaks, anyone with
-  it can take over the bot and start a chat as the first DM. Rotate via
-  [@BotFather](https://t.me/BotFather) immediately. Same applies to a leaked
-  ticlawk connector API key — revoke it from the ticlawk app.
+- **Agents can run code on your machine.** Whatever Claude Code / Codex /
+  OpenClaw / opencode / pi can do in the bound workdir, the Ticlawk app can
+  ask it to do. Treat the chat as you'd treat a shell.
+- **Single user.** The connector binds to one Ticlawk account. Don't share
+  your connector API key.
+- **Secrets stay local.** Connector API keys and binding metadata live in
+  `~/.ticlawk/.config` (mode `0600`) and never leave your machine. The
+  daemon listens on `127.0.0.1:8741` only — it does not bind to any external
+  interface.
+- **Token leak = remote shell.** If your Ticlawk connector API key leaks,
+  revoke it from the Ticlawk app immediately.
 - **No telemetry.** `ticlawk` does not send analytics or usage data
-  anywhere. The only outbound traffic is to Telegram (when the telegram
-  adapter is active) or to your configured ticlawk API URL (default
-  `ticlawk.com`, when the ticlawk adapter is active).
+  anywhere. The only outbound traffic is to your configured Ticlawk API URL
+  (default `ticlawk.com`).
 
 ---
 
 ## How it works
 
-1. You send a message in Telegram or ticlawk.
-2. The adapter delivers it to the local `ticlawk` daemon.
-3. The daemon routes it into the bound Claude Code / Codex / OpenClaw session
-   on your machine.
-4. The runtime replies; `ticlawk` captures the output (including
-   streaming tokens and supported artifacts).
-5. The reply goes back through the adapter to the same chat.
-
-For ticlawk inbound delivery, `ticlawk` keeps a WebSocket connection to
-the ticlawk connector wake endpoint. Wake events such as `jobs.available` and
-`bindings.changed` do not include message text, media, or task payloads. On wake,
-the local daemon uses the existing HTTP APIs to claim pending jobs and refresh
-channel bindings. The durable queue and `claim-pending` API remain the only
-ownership boundary. By default the wake endpoint is
+1. You send a message in the Ticlawk app.
+2. The Ticlawk backend enqueues a delivery for the bound agent.
+3. The local `ticlawk` daemon receives a wake event, claims the delivery,
+   and routes the message into the bound Claude Code / Codex / OpenClaw /
+   opencode / pi session on your machine.
+4. The runtime processes the turn; the agent uses the `ticlawk message send`
+   CLI to push chat replies back through the daemon to the app.
+
+`ticlawk` keeps a WebSocket connection to the Ticlawk connector wake
+endpoint. Wake events (`jobs.available`, `bindings.changed`) do not include
+message text or media. On wake, the local daemon uses HTTP APIs to claim
+pending work and refresh bindings. The durable queue and claim API remain
+the only ownership boundary. By default the wake endpoint is
 `wss://edge.ticlawk.com/functions/v1/connector-wake`; override it with
 `ticlawk.connector-ws-url` only for local development or advanced setups.
-Low-frequency recovery audits still run so a missed wake or reconnect window
-does not strand durable jobs; they stay slow and do not speed up when the wake
+Low-frequency recovery audits run so a missed wake or reconnect window does
+not strand durable jobs; they stay slow and do not speed up when the wake
 connection is disconnected.
 
-The daemon owns the binding — which adapter target talks to which local
-runtime, and the metadata needed to resume that runtime later. Adapters own
-their own authentication. That's the whole architecture.
+The daemon owns the binding — which Ticlawk conversation talks to which
+local runtime, and the metadata needed to resume that runtime later. That's
+the whole architecture.