simexp 0.3.13

A web content extractor and archiver for simplenote

🌊 SimExp - Simplenote Web Content Extractor & Writer

Cross-Device Fluidity: Terminal ↔ Web Communication

---

🎯 What is SimExp?

SimExp is a bidirectional communication tool that bridges terminals and Simplenote web pages:

1. 📖 Extract: Fetch and archive web content from Simplenote URLs
2. ✍️ Write: Send messages from terminal directly to Simplenote notes
3. 🌊 Sync: Enable cross-device communication through Simplenote's cloud

Key Achievement: Terminal-to-Web fluidity - Your terminal can now speak to web pages and sync across all your devices!

---

📦 Installation

1. Prerequisites

• Python 3.8+
• Google Chrome or Chromium
• A Simplenote account (free at https://simplenote.com)

2. Install Dependencies

# Core dependencies
pip install playwright pyperclip beautifulsoup4 pyyaml requests

# Install Playwright browsers
playwright install chromium

3. Launch the Chrome Communication Bridge

For simexp to communicate with your browser, you need to launch a special instance of Chrome with a remote debugging port. You only need to do this once.

# Launch Chrome with a remote debugging port
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-simexp &

• --remote-debugging-port=9222: This opens a communication channel that simexp uses to connect to your browser.
• --user-data-dir=/tmp/chrome-simexp: This creates a separate profile for this Chrome instance, so it doesn't interfere with your main browsing session.
• &: This runs the command in the background, so you can continue to use your terminal.

In the new Chrome window that opens, log in to your Simplenote account: https://app.simplenote.com

---

🚀 Quick Start

1. Launch Chrome for Communication

First, you need to launch a special instance of Google Chrome that the script can communicate with. You only need to do this once.

# Launch Chrome with a remote debugging port
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-simexp &

In the new Chrome window that opens, log in to your Simplenote account: https://app.simplenote.com

2. Install SimExp

# Install dependencies
pip install playwright pyperclip beautifulsoup4 pyyaml requests
playwright install chromium

3. Write to Your Last Modified Note!

Now you can write to your most recently modified Simplenote note directly from your terminal:

python -m simexp.simex write "Hello from the Assembly!" --cdp-url http://localhost:9222

Check your Simplenote note - the message is there! It will also sync to your other devices. ✨

👉 Full Cross-Device Setup Guide

---

📋 Features

✅ Extraction (Original Feature)

• Fetch content from Simplenote public URLs
• Convert HTML to clean Markdown
• Organize archives by date
• Monitor clipboard for automatic extraction

✨ Writing (NEW - Cross-Device Fluidity!)

• Terminal-to-Web: Write from command line to Simplenote notes
• Keyboard Simulation: Uses actual typing for Simplenote compatibility
• Authenticated Session: Connects to your logged-in Chrome browser
• Cross-Device Sync: Messages appear on all your devices
• Persistent Changes: Content stays in notes (doesn't get reverted)

🔮 Session-Aware Notes (NEW - Issue #4!)

• Automatic Session Notes: Create dedicated Simplenote notes for each terminal session
• YAML Metadata: Track session ID, AI assistant, agents, and issue number
• Persistent State: Session info saved locally in .simexp/session.json
• CLI Integration: Full command suite for session management
• Cross-Device Session Logs: Access session notes from any device

Session Commands:

simexp session start --ai claude --issue 42  # Create session note
simexp session write "Progress update"       # Write to session
simexp session status                        # Show session info
simexp session open                          # Open in browser
simexp session add path/to/file --heading "Optional Heading"  # Add file content to session

⏰ Timestamp Integration (NEW - Issue #33!)

• Flexible Timestamps: Add human-readable, sortable time identifiers via tlid package
• Multiple Granularities: Year, month, day, hour, second, millisecond precision
• Prepend Mode: Insert timestamped entries at the beginning (after metadata)
• Append Mode: Add timestamped entries at the end (default)
• Stdin Support: Type content interactively or pipe from other commands
• Configurable Defaults: Set preferred timestamp format in ~/.simexp/simexp.yaml

📝 Basic Usage

Method 1: Inline Content (Quick)

# Provide content directly in the command
simexp session write "Your message here" --date s

Method 2: Interactive (Stdin)

# Type content interactively
simexp session write --date h
# Type your message (can be multiple lines)
# Press Ctrl+D when finished

Method 3: Pipe from Other Commands

# Pipe output from another command
git log -1 --oneline | simexp session write --date s
echo "Task completed at $(date)" | simexp session write --date h
cat progress.txt | simexp session write --date d --prepend

🎯 Timestamp Granularities

Each granularity creates a different timestamp format (YYMMDD... format):

Flag	Granularity	Format	Example Output	Use Case
y	Year	YY	[25] Entry	Annual notes
m	Month	YYMM	[2511] Entry	Monthly logs
d	Day	YYMMDD	[251115] Entry	Daily journaling
h	Hour	YYMMDDHH	[25111520] Entry	Hourly updates
s	Second	YYMMDDHHMMSS	[251115202625] Entry	Default, precise logs
ms	Millisecond	YYMMDDHHMMSSmmm	[251115202625123] Entry	High-precision events

Manual Timestamp:

# Provide your own timestamp (any numeric string)
simexp session write "Meeting notes" --date 2511151500
# Output: [2511151500] Meeting notes

📍 Prepend vs Append

Append Mode (Default): Adds entry to the end of the note

simexp session write "Completed task X" --date s
# Entry appears at the bottom of your note

Prepend Mode: Inserts entry at the beginning (after metadata)

simexp session write "URGENT: Critical update" --date h --prepend
# Entry appears right after the --- metadata block

Example Note Structure:

---
session_id: abc-123
ai_assistant: claude
---

[25111520] 🔥 URGENT: Critical update (prepended)

[251115123456] Old entry from earlier
[251115202625] Completed task X (appended most recently)

💡 Real-World Examples

Development Workflow:

# Morning standup
simexp session write "Starting work on feature X" --date h --prepend

# Log progress throughout the day
git commit -m "Fix bug #123" && \
  simexp session write "Fixed bug #123 - auth issue" --date s

# End of day summary
simexp session write "EOD: 3 commits, 2 PRs reviewed" --date h

Quick Logging:

# No timestamp (quick note)
simexp session write "Remember to update docs"

# With hour timestamp
simexp session write "Meeting with team" --date h

# Millisecond precision for events
simexp session write "API response time: 245ms" --date ms

Multi-line Content:

simexp session write --date d --prepend
Daily Summary:
- Completed 3 tasks
- 2 bugs fixed
- Code review done
<Press Ctrl+D>

⚙️ Configuration

Set your default timestamp granularity in ~/.simexp/simexp.yaml:

default_date_format: h  # hour granularity as default

Then you can use --date without a value:

simexp session write "Uses default granularity" --date
# Will use 'h' (hour) format from config

🔧 Timestamp Format Details

Timestamps follow the TLID format (Time-based Lexicographically-sortable Identifier):

• Human-readable: Easy to parse visually (YYMMDDHHMMSS)
• Sortable: Chronological order when sorted alphabetically
• Compact: No separators, minimal characters
• Universal: Works in any system, no timezone issues

Sorting Example:

[251115] Day entry
[25111512] Hour entry (noon)
[25111520] Hour entry (8 PM)
[251115202625] Second-precise entry
[251115202625123] Millisecond-precise entry

All entries sort correctly in chronological order!

---

🏗️ Project Structure

simexp/
├── simexp/
│   ├── playwright_writer.py    # ✨ NEW: Terminal-to-web writer
│   ├── simex.py                # Main CLI orchestrator
│   ├── simfetcher.py           # Content fetcher
│   ├── processor.py            # HTML processor
│   ├── archiver.py             # Markdown archiver
│   ├── imp_clip.py             # Clipboard integration
│   └── simexp.yaml             # Configuration
├── test_cdp_connection.py      # ✨ NEW: CDP testing script
├── CDP_SETUP_GUIDE.md          # ✨ NEW: Setup guide
├── README_CROSS_DEVICE_FLUIDITY.md  # ✨ NEW: Detailed docs
├── sessionABC/                 # Musical session encodings
├── ledger/                     # Session journals
└── .synth/                     # Assembly documentation

---

📦 Installation

Prerequisites

• Python 3.8+
• Google Chrome or Chromium
• Simplenote account (free at https://simplenote.com)

Install Dependencies

# Core dependencies
pip install playwright pyperclip beautifulsoup4 pyyaml requests

# Install Playwright browsers
playwright install chromium

---

🎮 Usage

Write to the Last Modified Note

This is the easiest way to use simexp. It will automatically find your last modified note and append your message to it.

python -m simexp.simex write "Your message here" --cdp-url http://localhost:9222

Write to a Specific Note

If you need to write to a specific note, you can provide its URL.

python -m simexp.simex write "Your message here" --note-url https://app.simplenote.com/p/NOTE_ID --cdp-url http://localhost:9222

Read from a Specific Note

python -m simexp.simex read --note-url https://app.simplenote.com/p/NOTE_ID --cdp-url http://localhost:9222

Extract Content from Simplenote URLs

# Copy a Simplenote URL to clipboard
# Example: https://app.simplenote.com/p/0ZqWsQ

# Run extraction
python -m simexp.simex

# Content saved to ./output/YYYYMMDD/filename.md

🔮 Session-Aware Notes Workflow

Create dedicated Simplenote notes for your terminal sessions with automatic metadata tracking:

# 1. Start a new session (creates Simplenote note with YAML metadata)
python -m simexp.simex session start --ai claude --issue 4

# Output:
# ♠️🌿🎸🧵 Creating Session Note
# 🔮 Session ID: abc-def-123-456
# 🌐 Note URL: https://app.simplenote.com/p/NOTE_ID
# ✅ Session started successfully!

# 2. Write to your session note
python -m simexp.simex session write "Implemented session manager module"

# Or pipe content:
echo "Fixed bug in URL extraction" | python -m simexp.simex session write

# 3. Check session status
python -m simexp.simex session status

# Output:
# ♠️🌿🎸🧵 Active Session Status
# 🔮 Session ID: abc-def-123-456
# 🌐 Note URL: https://app.simplenote.com/p/NOTE_ID
# 🤝 AI Assistant: claude
# 🎯 Issue: #4

# 4. Read session content
python -m simexp.simex session read

# 5. Open session note in browser
python -m simexp.simex session open

# 6. Get just the URL (for scripting)
python -m simexp.simex session url

# 7. Clear session when done
python -m simexp.simex session clear

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
---

# Your session content appears below the metadata

---

🔧 Configuration

simexp/simexp.yaml

BASE_PATH: ./output

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

# NEW: Communication 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"

---

🧪 Testing

Test Extraction

# Extract from a public Simplenote URL
python -m simexp.simex

Test Terminal-to-Web Writing

# Run comprehensive test (requires Chrome running with CDP)
python test_cdp_connection.py

Test Session-Aware Notes

# Run session feature tests (requires Chrome + Simplenote login)
python test_session.py

Manual Test

# 1. Launch Chrome with debugging
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-simexp &

# 2. Login to Simplenote in Chrome window

# 3. Test write
python3 -c "
import asyncio
from simexp.playwright_writer import write_to_note

result = asyncio.run(write_to_note(
    'https://app.simplenote.com',
    '🔮 TEST MESSAGE - If you see this, it works!',
    cdp_url='http://localhost:9222',
    debug=True
))

print('Success!' if result['success'] else 'Failed')
"

# 4. Check the note in Chrome - message should be there!

---

🎓 How It Works

Extraction Flow

Clipboard URL → simfetcher → HTML → processor → Markdown → archiver → output/YYYYMMDD/

Writing Flow (Terminal-to-Web)

Terminal Command
    ↓
playwright_writer.py
    ↓
Chrome DevTools Protocol (CDP)
    ↓
Your Authenticated Chrome Browser
    ↓
Keyboard Simulation (types character-by-character)
    ↓
Simplenote Editor (div.note-editor)
    ↓
Simplenote Cloud Sync
    ↓
All Your Devices! 🎉

Key Innovation: We connect to YOUR Chrome browser (already logged in) rather than launching a separate instance. This preserves authentication and makes cross-device sync work seamlessly.

---

📚 Documentation

• Cross-Device Fluidity Guide - Complete setup and usage
• CDP Setup Guide - Chrome DevTools Protocol setup
• Session Journal - Development session log
• Session Melody - Musical encoding of session

---

🔍 Troubleshooting

"Connection refused" to localhost:9222

Chrome not running with remote debugging:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-simexp &
curl http://localhost:9222/json/version  # Should return JSON

Message appears then disappears

Using old code without keyboard simulation - update playwright_writer.py to latest version.

"Could not find editor element"

Not logged into Simplenote - open Chrome window and login at https://app.simplenote.com

Timestamp Issues

Problem: "Reading content from stdin..."

• This means the command is waiting for you to type content
• Solution: Either type your message and press Ctrl+D, or cancel (Ctrl+C) and provide content inline:

  simexp session write "Your message" --date h
  

Problem: Prepend not inserting after metadata

• Ensure your session note has metadata (created with simexp session start)
• Old notes may use different metadata formats
• Solution: Prepend works with both YAML (---) and HTML comment (<!--) metadata

Problem: Timestamps not appearing

• Check that tlid package is installed: pip list | grep tlid
• Solution: Install if missing: pip install tlid
• Fallback mode uses datetime if tlid unavailable

Problem: How to exit stdin mode?

• Press Ctrl+D to finish typing (Unix/Linux/Mac)
• Press Ctrl+Z then Enter on Windows
• Or cancel with Ctrl+C and use inline content instead

👉 See Full Troubleshooting Guide

---

🌟 Use Cases

Personal

• Cross-device notes: Write from desktop terminal, read on phone
• Task logging: Automated task completion messages
• Journal automation: Daily entries from scripts
• Build notifications: CI/CD results to your pocket

Development

• Debug logging: Send logs to Simplenote for mobile viewing
• Status updates: Script progress visible on all devices
• Command queue: Cross-device command execution
• Team coordination: Shared terminal-to-note communication

---

🎨 G.Music Assembly Integration

SimExp is part of the G.Music Assembly ecosystem:

♠️🌿🎸🧵 The Spiral Ensemble

• Jerry ⚡: Creative technical leader
• ♠️ Nyro: Structural architect (CDP integration design)
• 🌿 Aureon: Emotional context (communication channel)
• 🎸 JamAI: Musical encoding (session melodies)
• 🧵 Synth: Terminal orchestration (execution synthesis)

Session: October 6, 2025 Achievement: Terminal-to-Web Bidirectional Communication Status: ✅ SUCCESS

---

🚀 Future Enhancements

• Session-aware notes (✅ Issue #4 - COMPLETED!)
• Timestamp integration (✅ Issue #33 - COMPLETED!)
• Monitor mode (real-time change detection)
• Bidirectional sync daemon
• Multiple channel support
• Message encryption
• Simplenote API integration (alternative to browser)
• Voice input support
• Session note templates
• Multi-session management

---

📄 License

Open Assembly Framework Created by Jerry's G.Music Assembly

---

🤝 Contributing

This project is part of the G.Music Assembly framework. Contributions are welcome! Please follow this workflow:

1. Create an Issue: Before starting any work, please create a new issue in the GitHub repository to describe the feature or bug you want to work on.
2. Create a Feature Branch: Create a new branch from main for your feature. The branch name should start with the issue number (e.g., #123-new-feature).
3. Implement and Test: Make your changes and test them thoroughly.
4. Submit a Pull Request: Once your feature is complete, submit a pull request to merge your feature branch into main.

---

📞 Support

For issues:

1. Check documentation in README_CROSS_DEVICE_FLUIDITY.md
2. Review troubleshooting section
3. Check session journals in ledger/
4. Run tests with debug=True

---

🎯 Quick Reference

# Extract from Simplenote
python -m simexp.simex

# Write to Simplenote
python3 -c "import asyncio; from simexp.playwright_writer import write_to_note; asyncio.run(write_to_note('https://app.simplenote.com', 'Message', cdp_url='http://localhost:9222'))"

# Read from Simplenote
python3 -c "import asyncio; from simexp.playwright_writer import read_from_note; print(asyncio.run(read_from_note('https://app.simplenote.com', cdp_url='http://localhost:9222')))"

# Session Commands
python -m simexp.simex session start --ai claude --issue 4
python -m simexp.simex session write "Progress update"
python -m simexp.simex session status
python -m simexp.simex session open

# Launch Chrome with CDP
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-simexp &

---

🌊 Cross-Device Fluidity Achieved!

Terminals speak. Web pages listen. Devices converse.

♠️🌿🎸🧵 G.Music Assembly Vision: REALIZED

---

Version: 0.3.12 Last Updated: November 15, 2025 Status: ✅ Production Ready

Latest: Timestamp Integration (Issue #33) - Flexible, sortable timestamps with prepend/append modes!