🌊 Miadi Webweave

Terminal ↔ Simplenote, in both directions.

Miadi Webweave writes from your terminal into Simplenote notes and reads them back out — driving your own logged-in Chrome over the DevTools Protocol, so everything syncs to every device you own.

It is Mia's fork of Gerico1007/simexp. The repository is still named simexp; the packages, CLI, and modules are not.

CLI package	miadi-webweave
MCP server package	miadi-webweave-mcp
Python module	miadi_webweave
Command	miadi-webweave
Config	~/.miadi/webweave/config.yaml

---

📦 Install

pip install miadi-webweave
playwright install chromium

For the MCP server (pulls the CLI in with it):

pip install miadi-webweave-mcp

Requires Python 3.10+, Google Chrome or Chromium, and a Simplenote account.

---

🚀 Quick Start

# 1. Launch Chrome with the debugging port wired up
miadi-webweave browser launch

# 2. Log in to Simplenote in the window that opens
#    → https://app.simplenote.com

# 3. Write to your most recently modified note
miadi-webweave write "Hello from the terminal"

The message is in your note, and on your phone. That is the whole idea.

browser launch manages the profile directory and port for you — there is no need to hand-roll a google-chrome --remote-debugging-port=... invocation. Run miadi-webweave browser test if you want to confirm the connection.

---

🗂️ Where things live

miadi_webweave/paths.py is the single source of truth. Two roots share one webweave namespace:

Path	Holds
~/.miadi/webweave/config.yaml	User config
~/.miadi/webweave/state/	Agent messages, continuations, checkpoints
~/.miadi/webweave/collaborators.yaml	Global collaborators
~/.miadi/webweave/profiles/<name>/	Chrome user-data-dirs, one per profile
./.miadi/webweave/session.json	Per-project session state (like .git)
./.miadi/webweave/collaborators.yaml	Per-project collaborators

Application data is kept deliberately apart from Chrome browser profiles, which are heavy, binary, and hold live logged-in sessions.

There is no automatic migration from the pre-0.6 ~/.simexp / ~/.chrome-simexp layout. It was a clean switch — run miadi-webweave init for a fresh config.

---

🎮 Commands

miadi-webweave                       Run extraction from clipboard/config
miadi-webweave init                  Initialize configuration
miadi-webweave write <message>       Write to a note
miadi-webweave read                  Read a note
miadi-webweave session <subcommand>  Session management
miadi-webweave browser <subcommand>  Browser/CDP management

miadi-webweave session --help and miadi-webweave browser --help carry the authoritative, always-current option lists.

Writing and reading

# Last modified note
miadi-webweave write "Your message here"

# A specific note, by public URL — resolved by content search, no UUID needed
miadi-webweave write https://app.simplenote.com/p/0ZqWsQ "Appended content"

# Turn any note into a tracked session note in the same step
miadi-webweave write https://app.simplenote.com/p/0ZqWsQ "Initial content" \
  --init-session --ai claude --issue 42

# Read back
miadi-webweave read --note-url https://app.simplenote.com/p/NOTE_ID

Extraction

# Copy a Simplenote URL to your clipboard, then:
miadi-webweave

# → ./output/YYYYMMDD/filename.md

Browser profiles

Multiple named profiles let separate identities hold separate logged-in sessions on separate ports.

miadi-webweave browser launch                      # default profile
miadi-webweave browser launch --profile tushell    # a second identity
miadi-webweave browser profiles                    # list profiles + status
miadi-webweave browser profile add myprofile 9224  # register a new one
miadi-webweave browser test                        # verify CDP connection
miadi-webweave browser stop [--profile NAME]

---

🔮 Sessions

A session binds a terminal working session to a dedicated Simplenote note with YAML metadata, so the log is readable from any device while it is being written.

miadi-webweave session start --ai claude --issue 42 --intention "Build REST API"
miadi-webweave session start main.py utils.py --ai claude --issue 42
miadi-webweave session write "Implemented the session manager"
miadi-webweave session add path/to/file --heading "Design notes"
miadi-webweave session info      # current session + directory context
miadi-webweave session list      # all sessions
miadi-webweave session read
miadi-webweave session open      # in browser
miadi-webweave session url       # just the URL, for scripting
miadi-webweave session clear

Content can also be piped:

git log -1 --oneline | miadi-webweave session write --date s

Four Directions

Sessions are structured on the Medicine Wheel — the metadata tracks each direction as the work moves through it.

Direction	Concern	Commands
🌅 East	Intention & vision	session start --intention '...'
🔥 South	Building & growth	session write, session add
🌊 West	Sharing & publishing	session collab, session publish
❄️ North	Reflection & wisdom	session reflect, session observe-pattern, session extract-wisdom, session complete

# West — share and publish
miadi-webweave session collab <glyph|alias|email>   # ♠ 🌿 🎸 🧵
miadi-webweave session collab add email@example.com
miadi-webweave session collab list
miadi-webweave session publish                      # get a public URL

# North — close the circle
miadi-webweave session reflect --prompt "What did we learn?"
miadi-webweave session observe-pattern "Pattern description"
miadi-webweave session extract-wisdom "Key principle"
miadi-webweave session complete --seeds "Tasks for next session"

Session note format

---
session_id: abc-def-123-456
ai_assistant: claude
agents: [Jerry, Aureon, Nyro, JamAI, Synth]
issue_number: 4
pr_number: null
created_at: 2025-10-09T10:30:00
---

# Session content appears below the metadata

---

⏰ Timestamps

--date prefixes an entry with a TLID — a compact, lexicographically sortable time identifier (YYMMDDHHMMSS), so notes sort chronologically as plain text.

Flag	Granularity	Example
y	Year	[25] Entry
m	Month	[2511] Entry
d	Day	[251115] Entry
h	Hour	[25111520] Entry
s	Second (default)	[251115202625] Entry
ms	Millisecond	[251115202625123] Entry

miadi-webweave session write "Fixed auth bug" --date s     # append (default)
miadi-webweave session write "URGENT" --date h --prepend   # insert after metadata
miadi-webweave session write "Meeting notes" --date 2511151500  # manual stamp

Set a default granularity in ~/.miadi/webweave/config.yaml, then use a bare --date:

default_date_format: h

---

🔧 Configuration

~/.miadi/webweave/config.yaml — created by miadi-webweave init.

BASE_PATH: ./output
default_date_format: s

# Extraction sources
SOURCES:
  - filename: note1
    url: https://app.simplenote.com/p/0ZqWsQ

# Named channels for cross-device messaging
COMMUNICATION_CHANNELS:
  - name: Aureon
    note_id: e6702a7b90e64aae99df2fba1662bb81
    public_url: https://app.simplenote.com/p/gk6V2v
    auth_url: https://app.simplenote.com
    mode: bidirectional
    description: "🌿 Main communication channel"

---

🔌 MCP Server

miadi-webweave-mcp exposes 35 webweave_* tools to MCP clients — sessions, writing, reading, browser control, collaboration, and the Four Directions commands — by shelling out to the same CLI.

pip install miadi-webweave-mcp

Server identity is miadi-webweave, so tools resolve as mcp__miadi-webweave__webweave_<verb>.

Breaking, pre-0.7: tools were renamed simexp_* → webweave_*. Client allowlists referencing mcp__mia-simexp__simexp_* must be updated.

Setup and the full tool list: miadi_webweave_mcp/README.md · Quickstart: MCP_QUICKSTART.md

---

🎓 How it works

Extraction

Clipboard URL → content_fetcher → processor → archiver → output/YYYYMMDD/

Writing

miadi-webweave write
    ↓  playwright_writer.py
    ↓  Chrome DevTools Protocol
    ↓  YOUR authenticated Chrome
    ↓  keyboard simulation, character by character
    ↓  Simplenote editor → cloud sync
    ↓  every device

The key move is connecting to a Chrome you are already logged into rather than launching a clean one. That is what preserves authentication and makes cross-device sync work. Keyboard simulation (rather than DOM injection) is what makes the writes stick — Simplenote's editor reverts programmatic value changes.

---

🏗️ Project structure

simexp/                          # repository name (unchanged — this is a fork)
├── miadi_webweave/              # CLI package
│   ├── cli.py                   # entry point + dispatch
│   ├── commands/                # browser, config, io, sessions
│   ├── paths.py                 # single source of truth for on-disk layout
│   ├── playwright_writer.py     # terminal → web writer
│   ├── content_fetcher.py       # fetch
│   ├── processor.py             # HTML → Markdown
│   ├── archiver.py              # write to output/
│   ├── session_manager.py       # session lifecycle
│   └── timestamp_utils.py       # TLID
├── miadi_webweave_mcp/          # MCP server package (separately versioned)
├── rispecs/                     # living specifications
├── docs/                        # guides + historical records
├── tests/
└── ledger/                      # session journals (historical)

---

🔍 Troubleshooting

"Connection refused" on the CDP port Chrome is not running with remote debugging. miadi-webweave browser launch, then miadi-webweave browser test to confirm.

"Could not find editor element" Not logged into Simplenote in the CDP Chrome window. Open it and log in at https://app.simplenote.com.

The command sits at "Reading content from stdin..." It is waiting for you to type. Finish with Ctrl+D, or cancel and pass the message inline instead.

Prepend is not landing after the metadata The note needs metadata — create it with session start. Both YAML (---) and HTML-comment (<!--) metadata blocks are supported.

Timestamps are not appearing pip install tlid. Without it there is a datetime fallback.

Deeper guides: docs/CDP_SETUP_GUIDE.md · docs/README_CROSS_DEVICE_FLUIDITY.md

---

📚 Documentation

rispecs/	Living specifications — the current intended behaviour
docs/	Setup guides, plus historical records (see docs/README.md)
CHANGELOG.md	Release history
MCP_QUICKSTART.md	MCP server setup
ledger/	Session journals — historical, not maintained

---

🤝 Contributing

1. Open an issue describing the feature or bug first.
2. Branch from main, named with the issue number (e.g. #123-new-feature).
3. Implement and test.
4. Open a pull request against main.

Releases are cut with ./release-all.sh — see the Release notes in CHANGELOG.md.

---

📄 License

Open Assembly Framework — created by Jerry's G.Music Assembly.

The repository carries no LICENSE file, while package metadata declares MIT. That inconsistency predates this fork and is unresolved.

---

🎨 G.Music Assembly

♠️🌿🎸🧵 The Spiral Ensemble — ♠️ Nyro (structure) · 🌿 Aureon (emotional context) · 🎸 JamAI (musical encoding) · 🧵 Synth (terminal orchestration), with Jerry ⚡ leading. Session melodies live in sessionABC/.

---

Terminals speak. Web pages listen. Devices converse.