coaia-visualizer

Overview

coaia-visualizer is the dedicated client-side application for visualizing and interacting with data generated by the coaia-narrative system. It transforms raw JSONL (JSON Lines) data, representing Structural Tension Charts and Multi-Universe Narrative Beats, into an intuitive and interactive user interface.

This tool allows users to upload their coaia-narrative memory files and gain clear insights into their creative projects, understanding the dynamic interplay of their Desired Outcomes, Current Realities, and Action Steps, alongside the rich context of Narrative Beats.

NEW: Now includes REST API and MCP server for AI agent access! See Feature 4 Documentation.

Key Features

Web Interface

• Local JSONL File Upload & Export: Securely upload coaia-narrative JSONL files from your local system for visualization and export the processed data back.
• Hierarchical Chart Visualization: Explore your Structural Tension Charts in both a comprehensive list view and an expandable, nested hierarchy, revealing master charts and their telescoped sub-charts.
• Detailed Chart Inspector: Select any chart to access a detailed view, showcasing its Desired Outcome, Current Reality, metadata (creation/due dates, level), and associated components.
• Dynamic Structural Tension Display: Clearly distinguishes and presents the core Desired Outcome and Current Reality observations, making the generative force of structural tension visible.
• Action Step Tracking: View all Action Steps for a selected chart, complete with their descriptions, completion status, and due dates, facilitating a clear understanding of strategic advancement.
• Narrative Beat Integration: Displays associated Narrative Beats, offering multi-universe perspectives (Engineer-World, Ceremony-World, Story-Engine-World) to enrich the context of your creative efforts.
• Inter-Chart Relation Graph: Visualizes the relationships between charts and entities, illustrating how different creative projects and their components are interconnected.
• Data Statistics Overview: Provides summary statistics of the loaded data, including total charts, entities, and relations, for quick comprehension of your creative landscape.

API & Agent Access ✨ NEW

• REST API: Full CRUD operations on charts via HTTP endpoints
• Token Authentication: Secure access with COAIAN_API_TOKEN
• MCP Server: Model Context Protocol server for AI agents (Claude Desktop)
• Agent Tools: 11 tools for listing, creating, updating, and searching charts
• Automatic Backups: All write operations create timestamped backups
• See feat-4-mcp-api/ for complete documentation

Technologies Used

• Framework: Next.js
• Language: TypeScript
• UI Library: React
• Styling: Tailwind CSS with Radix UI components (for accessible and customizable UI)
• Charting: recharts (for potential future data visualizations)
• Form Management: react-hook-form
• Schema Validation: zod

Getting Started

Web Interface

1. Clone the repository: ```bash git clone cd coaia-visualizer ```
2. Install dependencies: ```bash pnpm install ```
3. Run the development server: ```bash pnpm run dev ```
4. Open your browser to http://localhost:3000 (or the port indicated by pnpm run dev).
5. Upload a coaia-narrative generated JSONL file to begin visualizing your creative projects.

CLI Mode (with Local Memory File)

```bash

Install globally or use npx

npm install -g coaia-visualizer

Launch with local memory file

coaia-visualizer --memory-path ./memory.jsonl

Set API token for agent access

export COAIAN_API_TOKEN=$(openssl rand -hex 32) coaia-visualizer --memory-path ./memory.jsonl ```

API & Agent Access

See complete setup in feat-4-mcp-api/SETUP_GUIDE.md

Quick start: ```bash

1. Set API token

export COAIAN_API_TOKEN=your_secure_token

2. Start visualizer

coaia-visualizer --memory-path memory.jsonl

3. Test API

curl -H "Authorization: Bearer $COAIAN_API_TOKEN"
http://localhost:3000/api/charts

4. Configure Claude Desktop (see setup guide)

```

Deployment

Your project is live at:

https://vercel.com/jgwills-projects/v0-jsonl-visualizer

Build your app

Continue building your app on:

https://v0.app/chat/drYe7XUyCIv

How It Works (v0.app Integration)

1. Create and modify your project using v0.app.
2. Deploy your chats from the v0 interface.
3. Changes are automatically pushed to this repository.
4. Vercel deploys the latest version from this repository.