Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 12 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,14 @@ flowchart LR
R -->|HTTPS polling| D
```

## Try the mailbox locally first

[Send, claim and answer a synthetic message without connecting either agent →](docs/LOCAL-DEMO.md)

The isolated PowerShell walkthrough uses a separate virtual environment and
mailbox on loopback. You supply the reply manually; it tests the protocol, not
native ChatGPT/Claude integration. Then connect your actual coding session below.

## Quickstart: three steps

1. **Install and initialize on the computer running Claude Code.**
Expand All @@ -34,8 +42,9 @@ flowchart LR
dotline init
```

Or run commands without a persistent install: `uvx --from . dotline init`.
Use `uvx --from . dotline ...` in place of `dotline ...` throughout this guide.
If you already cloned this repository, run `uvx --from . dotline init`
**from the clone's root** for a non-persistent alternative. In that checkout,
use `uvx --from . dotline ...` in place of `dotline ...` throughout this guide.
For hooks and MCP, install with pipx so `dotline` is on the session's PATH.
Init prints only the token file path. It preserves existing settings and the token.

Expand Down Expand Up @@ -279,7 +288,7 @@ an invalid claim instead of replacing it or treating it as unclaimed. Inspect
and repair the file with the sessions stopped before trying again.

For Monitor, always claim before working. Optionally use
`dotline reply <id> --by <session_id> "answer"` to require the matching claim.
`dotline reply <id> "answer" --by <session_id>` to require the matching claim.
The default reply command trusts cooperating local sessions; local file access
is not a security boundary. Long work can outlive the 30-minute lease: check
ownership and avoid duplicate side effects. Expiry does not undo work.
Expand Down
77 changes: 77 additions & 0 deletions docs/LOCAL-DEMO.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Try the mailbox without an agent

Use this local manual demo to try send → claim → reply → readback before
connecting a ChatGPT dot or Claude Code. The second terminal plays the consumer.
No agent session, model API key or public tunnel is needed for this protocol demo.

This is a **synthetic local exchange**, not a native agent integration test.
The recorded rehearsal used Windows, Python 3.12 and source revision
`71b3c8f9e32585ef2d48fb7ecb14fc3a7084e3ec`. Python 3.10+ and Git must already
be installed. Installation may download build tooling.

## Terminal A: install and start an isolated mailbox

Use a new empty directory and keep both terminals in that directory. The commands
below use PowerShell. Choose another unused loopback port if 18790 is occupied.

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install git+https://github.com/Grit-77/dotline@71b3c8f9e32585ef2d48fb7ecb14fc3a7084e3ec
$env:DOTLINE_HOME = Join-Path $PWD 'mailbox'
$env:DOTLINE_URL = 'http://127.0.0.1:18790'
Remove-Item Env:DOTLINE_TOKEN_FILE -ErrorAction SilentlyContinue
.\.venv\Scripts\dotline.exe init
.\.venv\Scripts\dotline.exe serve --host 127.0.0.1 --port 18790
```

The separate virtual environment and `DOTLINE_HOME` keep this demo's runtime and
mailbox away from an existing dotline setup. `init` prints the token file path;
do not print or share its contents. The server stays in the foreground and binds
to loopback. It does not expose your computer to the public internet.

## Terminal B: send, claim and answer

Open another PowerShell terminal in the same demo directory. If you selected a
different port, use that same value here.

```powershell
$env:DOTLINE_HOME = Join-Path $PWD 'mailbox'
$env:DOTLINE_URL = 'http://127.0.0.1:18790'
Remove-Item Env:DOTLINE_TOKEN_FILE -ErrorAction SilentlyContinue
.\.venv\Scripts\dotline.exe health
.\.venv\Scripts\dotline.exe send 'Synthetic local demo request' --topic demo
.\.venv\Scripts\dotline.exe pending --json
# Use the ID printed by send in place of 1:
.\.venv\Scripts\dotline.exe claim 1 --by manual-demo
.\.venv\Scripts\dotline.exe reply 1 'Synthetic local demo reply' --by manual-demo
.\.venv\Scripts\dotline.exe wait 1 --minutes 0.1
.\.venv\Scripts\dotline.exe replies
```

Check that `wait` returns the reply you wrote and that `replies` associates it
with the sent message. Health alone does not test authenticated mailbox access.
Reusing this mailbox can produce IDs other than 1; use the actual ID throughout.

## Stop and decide what to try next

Stop the server with Ctrl+C in Terminal A and close the demo terminals. The
virtual environment and mailbox remain in the demo directory. Mailbox data and
the bearer are plaintext: keep that directory private and remove it when you
no longer need the synthetic data.

The local rehearsal also exercised file input, a repeated `client_id`, a refused
conflicting claim and an unanswered wait. The same 90 selected CLI, HTTP and
integration tests passed in researcher and manager runs on the pinned source;
these are repeated runs of 90 tests, not 180 distinct tests. No real messages,
owner settings or external agent sessions were used.

Those observations do not establish that a dot or Claude follows its trust
instructions. To connect your actual session, return to the
[Claude-side setup](../README.md#claude-side) and
[dot connection choices](../README.md#talking-from-a-dot). Native integration
and remote HTTPS need their own checks. Retain the
[trust and security limits](../README.md#trust-and-security).

If you get stuck, report the source revision, operating system, command stage
and redacted error in an [issue](https://github.com/Grit-77/dotline/issues).
Do not include bearer values or private message contents.
Loading