Asynkron.LiveView - CLI AI Companion

A live view system for markdown files that automatically detects changes and streams a focused, per-file markdown view alongside a live directory browser.

---

Why This Matters

When working with CLI-based AI agents such as Codex CLI or CoPilot CLI, you often get streams of progress, design discussions, reasoning, and plans logged as markdown into a folder (for example /logs).

Asynkron.LiveView connects to that folder and instantly visualizes the evolving state of the agent’s thoughts. This gives you a real-time debugging and mental model helper:

• See the agent’s reasoning unfold as structured markdown
• Follow design decisions as they develop
• Inspect progress logs in chronological order
• Visualize system diagrams and flows directly with Mermaid.js
• Keep context without digging through scattered files

Instead of reading static logs or scrolling endlessly in a terminal, you get a clear, dynamic, and live view of what your AI agent is doing.

How to

• Open a browser to: http://localhost:8080/?path={path-to-your-markdown-logs}.
• Example: http://localhost:8080/?path=~/git/asynkron/Asynkron.DurableFunctions/Logs

Inside your own project repository

Create a folder for your markdown logs, e.g. /logs.
You can decide if you want to keep the logs as part of your git history, a form of architectural records.
Or simply .gitignore the contents.

Update your agents.md (or similar file depending on agent) to something similar to this:

## CLI
- when working using in the CLI, I want you to place markdown files into a /logs directory. we have a special viewer that display any new content there. we can show mermaid diagrams, code diffs, code snippets, architectural plans etc.

Example log file: `log{unixtimestamp}.md` - always use the current unix timestamp to ensure unique filenames.

 Boring activities:
 ### 2025-09-27 17:20 CEST — MultiHost Soak Test Initiated
 * ✅ Goal: repeat Category=MultiHost suite for 5 consecutive passes.
 * ✅ Loop cadence: sequential runs, capturing per-iteration duration & status.
 * ✅ Environment: local Testcontainers PostgreSQL (auto-provisioned per run).
 * ⚠️ Something broke a bit.
 * ❌ Something terrible happened

 Infographics / Examples
 // Mermaid diagrams - use often, class, sequence and flow charts. make sure to escpae { ( node and other reserved chars in mermaid syntax
 // Relevant Code blocks
 // Test result table + summary
 // Log snippets.

 Success stories, we completed some larger work
 ### 2025-09-27 17:20 CEST — VICTORY!
 * ⭐️ We did it! All tests passed!
 * ⭐️ Everything is awesome!
 * 🎉 5/5 passes of Category=MultiHost suite.

---

### Always add log files when:

1. building the project
- report build success or failure
- include any relevant build errors
2. running tests
   - report test success or failure
   - include test summary and any relevant test failures
3. making any code changes
   - include code diffs or snippets of the changes made, whichever makes most sense
4. completing any significant task
   - include a summary of what was accomplished
   - highlight any important details or next steps
5. every 15 minutes if nothing else has happened
   - provide a brief status update
   - mention any ongoing tasks or upcoming milestones
6. whenever you make a plan or change a plan
   - outline the new plan or changes made
   - explain the reasoning behind the changes
   - confirm with user that the plan aligns with their goals
7. whenever you think the user would benefit from an update
   - use your judgment to determine when an update is warranted
- consider the user's perspective and what information would be most helpful

---

Features

• 📄 Single-file Focus: Render one markdown file at a time while keeping the familiar per-file controls for downloading, raw view, and deletion.
• 📁 Directory Browser: A live sidebar lists every markdown file under the chosen root. Click a file to switch the main view instantly.
• 🔄 Real-time Updates: The browser stays connected over WebSocket to reflect new files, deletions, or edits without a manual refresh.
• 🧭 Deep Linking: Use query parameters like ?path=~/logs&file=session.md to open a specific directory and file directly.
• 🎨 Rich Rendering: Markdown is rendered with syntax highlighting and Mermaid diagram support out of the box.

---

Installation & Quick Start

The project now ships as a Node.js monorepo with separate backend and frontend workspaces under apps/. You only need a recent Node.js runtime (v18 or newer is recommended) and npm to get started.

1. Install dependencies

npm install

2. Build the frontend bundle

npm run frontend:build

This compiles the static assets into apps/backend/public/static/dist, ready to be served by the Node backend.

3. Start the backend

npm run backend:dev -- --path markdown --port 8080

The CLI flags mirror the original Python server: --path selects the markdown directory to watch and --port defines the listening port. Omit both to use the defaults.

4. Open your browser

Navigate to http://localhost:8080/?path=/path/to/markdown to view your log directory.

✅ Project structure & tooling

apps/
  backend/   # Express-based markdown server
    public/  # HTML shell plus compiled frontend assets
    src/     # Server implementation and helpers
    tests/   # Vitest coverage for server modules
  frontend/  # Browser UI written in vanilla JS modules
    src/     # Client-side controllers and styles
    tests/   # Node test suites for shared utilities
markdown/    # Sample workspace watched by default

Common scripts are exposed from the repository root:

• npm run backend:start – launch the production server
• npm run backend:dev – run the backend with development logging
• npm run frontend:build – rebuild the static bundle
• npm test – execute all workspace test suites

Each workspace also exposes linting and formatting commands that share the root ESLint/Prettier configuration. Run them with npm run lint --workspaces or target a specific package via npm run lint --workspace <package-name>.

Add Markdown Files

Drop .md files into the watched directory and the viewer will list them automatically. Append &file=your-file.md to the URL to open a specific file.

Backend environment options

The backend respects standard environment variables when you run the npm scripts:

# Choose a different port
PORT=3000 npm run backend:start

# Watch a different directory
MARKDOWN_DIR=~/git/asynkron/DemoIf/docs npm run backend:start

Usage

Linking to directories and files

• path (required): Absolute or ~-prefixed directory to watch.
• file (optional): Markdown file relative to the chosen directory.
• Example: http://localhost:8080/?path=~/git/asynkron/DemoIf/docs&file=overview.md

Directory updates

• The client keeps a persistent WebSocket connection to /ws.
• Any new, modified, or removed markdown files trigger directory refreshes.
• When the open file changes on disk it is reloaded automatically.

API Endpoints

Endpoint	Description
GET /	Render the HTML application. Supports path and file query parameters.
GET /api/files	Return the markdown file list for the requested directory.
GET /api/file	Fetch a single file's content. Expects path and file.
GET /api/file/raw	Download a file as plain text.
DELETE /api/file	Delete a markdown file.
GET /ws	WebSocket endpoint that streams directory updates.

Development

Running Tests

npm test