chasm-cli 1.3.0

---

Chasm extracts and unifies chat sessions from AI coding assistants like GitHub Copilot, Cursor, and more. Never lose your AI conversations again.

✨ Features

• 🔍 Harvest - Extract chat sessions from VS Code, Cursor, Windsurf, and other editors
• 🔀 Merge - Combine sessions across workspaces and time periods
• 📊 Analyze - Get statistics on your AI assistant usage
• 🔌 API Server - REST API for building custom integrations
• 🤖 MCP Tools - Model Context Protocol support for AI agent integration
• 🗃️ Universal Database - SQLite-based storage that normalizes all providers

📦 Installation

From crates.io

cargo install chasm

From source

git clone https://github.com/nervosys/chasm.git

cd chasm

cargo install --path .

Pre-built binaries

Download from GitHub Releases:

Platform	Download
Windows x64	chasm-windows-x64.zip
macOS x64	chasm-darwin-x64.tar.gz
macOS ARM	chasm-darwin-arm64.tar.gz
Linux x64	chasm-linux-x64.tar.gz

Docker

docker pull ghcr.io/nervosys/chasm:latest

docker run -v ~/.chasm:/data ghcr.io/nervosys/chasm list workspaces

🚀 Quick Start

List discovered workspaces

chasm list workspaces

┌────────────────────────┬──────────────────┬──────────┬────────────┐
│ Name                   │ Provider         │ Sessions │ Updated    │
├────────────────────────┼──────────────────┼──────────┼────────────┤
│ my-project             │ GitHub Copilot   │ 15       │ 2026-01-08 │
│ another-project        │ Cursor           │ 8        │ 2026-01-07 │
│ open-source-contrib    │ GitHub Copilot   │ 23       │ 2026-01-06 │
└────────────────────────┴──────────────────┴──────────┴────────────┘

Show sessions for a project

chasm show path /path/to/your/project

Harvest sessions from VS Code

chasm harvest

Export a session to Markdown

chasm export session abc123 --format markdown --output chat.md

Start the API server

chasm api serve --port 8787

📖 CLI Reference

Core Commands

Command	Description
chasm list workspaces	List all discovered workspaces
chasm list sessions	List sessions (optionally filtered by workspace)
chasm list orphaned	List unregistered sessions on disk
chasm show session <id>	Display full session content
chasm show path <path>	Show sessions for a project path
chasm find workspace <pattern>	Search workspaces by name
chasm find session <pattern>	Search sessions by content

Data Management

Command	Description
chasm harvest scan	Scan for available providers and sessions
chasm harvest run	Collect sessions from all providers
chasm harvest status	Show harvest database status
chasm merge workspace <name>	Merge sessions from a workspace
chasm export session <id>	Export session to file
chasm import <file>	Import sessions from file

Session Recovery

Command	Description
chasm detect orphaned <path>	Find orphaned sessions in old workspace hashes
chasm detect orphaned -r <path>	Recover orphaned sessions to active workspace
chasm register all --path <path>	Register on-disk sessions in VS Code's index

Recovering Lost Chat History

When VS Code creates a new workspace hash (e.g., after reinstall or path change), your chat sessions may become "orphaned" in the old workspace folder. Use these commands to recover them:

# 1. Scan for orphaned sessions

chasm detect orphaned /path/to/project


# 2. Recover them (copy to active workspace)

chasm detect orphaned --recover /path/to/project


# 3. Register in VS Code's database

chasm register all --force --path /path/to/project


# 4. Reload VS Code (Ctrl+Shift+P -> Developer: Reload Window)

Server

Command	Description
chasm api serve	Start the REST API server
chasm mcp serve	Start the MCP tool server

Options

chasm --help          # Show all commands

chasm <cmd> --help    # Show help for a specific command

chasm --version       # Show version

🔌 API Server

Start the REST API server for integration with web/mobile apps:

chasm api serve --host 0.0.0.0 --port 8787

Endpoints

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/workspaces	List workspaces
GET	/api/workspaces/:id	Get workspace details
GET	/api/sessions	List sessions
GET	/api/sessions/:id	Get session with messages
GET	/api/sessions/search?q=	Search sessions
GET	/api/stats	Database statistics
GET	/api/providers	List supported providers
GET	/api/agents	List available agents

Example

curl http://localhost:8787/api/stats

{
  "success": true,
  "data": {
    "totalSessions": 330,
    "totalMessages": 19068,
    "totalWorkspaces": 138,
    "totalToolInvocations": 122712
  }
}

🤖 MCP Integration

Chasm provides Model Context Protocol tools for AI agent integration:

chasm mcp serve

Available Tools

• chasm_list_workspaces - List all workspaces
• chasm_list_sessions - List sessions in a workspace
• chasm_get_session - Get full session content
• chasm_search_sessions - Search across all sessions
• chasm_get_stats - Get database statistics

🤖 Agency (Agent Development Kit)

Agency is Chasm's Rust-native framework for building, orchestrating, and deploying AI agents. It provides a complete toolkit for creating autonomous agents that can reason, use tools, and collaborate in multi-agent workflows.

Key Capabilities

Feature	Description
🏗️ Code-First Agents	Define agents in Rust with type safety and performance
🔧 Tool Ecosystem	Built-in tools + custom function registration
🎭 Multi-Agent Orchestration	Sequential, parallel, hierarchical, and swarm patterns
🧠 Memory & RAG	Vector store, knowledge base, context window management
📡 Streaming	Real-time response streaming via SSE
🏠 Proactive Agents	Autonomous household and business agents
🌐 Distributed Execution	Remote task monitoring across machines
🎨 Multimodal	VLM/VLA support for vision and robotics

CLI Commands

# List available agents and roles

chasm agency list

chasm agency list --verbose


# Get detailed agent information

chasm agency info researcher


# Run an agent with a prompt

chasm agency run --agent researcher "What are the latest trends in AI?"

chasm agency run --agent coder --model gpt-4o "Write a REST API in Rust"


# Multi-agent orchestration

chasm agency run --orchestration sequential "Build and test a web scraper"

chasm agency run --orchestration parallel "Research AI, blockchain, and quantum computing"

chasm agency run --orchestration swarm "Design a microservices architecture"


# Create a custom agent

chasm agency create my-agent --role coder --instruction "You are a Rust expert"


# List available tools and templates

chasm agency tools

chasm agency templates

chasm agency modes

Agent Roles

Role	Icon	Description
coordinator	[C]	Manages and delegates tasks to other agents
researcher	[R]	Gathers information and analyzes data
coder	[D]	Writes and modifies code
reviewer	[V]	Reviews code and provides feedback
executor	[E]	Executes commands and tools
writer	[W]	Creates documentation and content
tester	[T]	Writes and runs tests
analyst	[A]	Data analysis and insights
household	[H]	Home automation and management
business	[B]	Business process automation
custom	[X]	User-defined agent with custom behavior

Orchestration Modes

Mode	Pattern	Description
single	[1]	Traditional single-agent response
sequential	[>]	Agents execute one after another, passing results
parallel	[‖]	Multiple agents work simultaneously on subtasks
loop	[O]	Agent repeats until a condition is met
hierarchical	[H]	Lead agent delegates to specialized sub-agents
swarm	[S]	Multiple agents collaborate with a coordinator

---

📚 Agency Use Cases

1. Research Assistant

Build an agent that searches the web, analyzes sources, and synthesizes findings:

use chasm::agency::{AgentBuilder, Runtime, Tool};

let researcher = AgentBuilder::new("researcher")
    .model("gemini-2.0-flash")
    .instruction("You are a research assistant. Search for information, 
                  analyze multiple sources, and provide comprehensive summaries 
                  with citations.")
    .tool(Tool::web_search())
    .tool(Tool::file_write())
    .temperature(0.5)
    .build();

let runtime = Runtime::new();
let result = runtime.run(&researcher, "What are the latest breakthroughs in fusion energy?").await?;

CLI equivalent:

chasm agency run --agent researcher "What are the latest breakthroughs in fusion energy?"

2. Code Review Pipeline

Chain multiple agents for thorough code review:

use chasm::agency::{Pipeline, AgentBuilder, OrchestrationType};

// Security reviewer
let security = AgentBuilder::new("security-reviewer")
    .role(AgentRole::Reviewer)
    .instruction("Review code for security vulnerabilities: injection, XSS, 
                  authentication issues, secrets exposure.")
    .build();

// Performance reviewer
let performance = AgentBuilder::new("perf-reviewer")
    .role(AgentRole::Reviewer)
    .instruction("Analyze code for performance issues: N+1 queries, 
                  memory leaks, inefficient algorithms.")
    .build();

// Style reviewer
let style = AgentBuilder::new("style-reviewer")
    .role(AgentRole::Reviewer)
    .instruction("Check code style, naming conventions, and documentation.")
    .build();

// Sequential pipeline: security → performance → style
let pipeline = Pipeline::sequential(vec![security, performance, style]);
let result = runtime.run_pipeline(&pipeline, code_to_review).await?;

CLI equivalent:

chasm agency run --orchestration sequential "Review this code: [paste code]"

3. Full-Stack Development Swarm

A coordinator delegates to specialized agents:

use chasm::agency::{Swarm, AgentBuilder, AgentRole};

// Coordinator
let coordinator = AgentBuilder::new("lead-dev")
    .role(AgentRole::Coordinator)
    .instruction("You are a tech lead. Break down tasks and delegate to:
                  - frontend-dev: React/TypeScript UI work
                  - backend-dev: Rust API development
                  - devops: Docker, CI/CD, deployment")
    .build();

// Specialist agents
let frontend = AgentBuilder::new("frontend-dev")
    .role(AgentRole::Coder)
    .instruction("Expert in React, TypeScript, TailwindCSS")
    .tool(Tool::file_read())
    .tool(Tool::file_write())
    .build();

let backend = AgentBuilder::new("backend-dev")
    .role(AgentRole::Coder)
    .instruction("Expert in Rust, Actix-web, SQLite")
    .tool(Tool::file_read())
    .tool(Tool::file_write())
    .tool(Tool::terminal())
    .build();

let devops = AgentBuilder::new("devops")
    .role(AgentRole::Executor)
    .instruction("Expert in Docker, GitHub Actions, cloud deployment")
    .tool(Tool::terminal())
    .build();

let swarm = Swarm::new(coordinator, vec![frontend, backend, devops]);
let result = runtime.run_swarm(&swarm, "Build a user authentication system").await?;

CLI equivalent:

chasm agency run --orchestration swarm "Build a user authentication system"

4. Automated Testing Agent

An agent that writes and runs tests:

use chasm::agency::{AgentBuilder, AgentRole, Tool};

let tester = AgentBuilder::new("test-writer")
    .role(AgentRole::Tester)
    .instruction("You write comprehensive tests. For each function:
                  1. Identify edge cases and boundary conditions
                  2. Write unit tests with clear assertions
                  3. Add integration tests where appropriate
                  4. Run tests and fix failures")
    .tool(Tool::file_read())
    .tool(Tool::file_write())
    .tool(Tool::terminal())  // For running tests
    .max_tool_calls(20)
    .build();

let result = runtime.run(&tester, "Write tests for src/auth/login.rs").await?;

5. Proactive Household Agent

An autonomous agent that monitors and manages home tasks:

use chasm::agency::{ProactiveMonitor, household_agent_config, PermissionLevel};

let config = household_agent_config()
    .permission_level(PermissionLevel::MediumRisk)  // Can take moderate actions
    .scan_interval(Duration::from_secs(3600))       // Check hourly
    .notifications_enabled(true)
    .integrations(vec!["google_calendar", "todoist", "smart_home"]);

let monitor = ProactiveMonitor::new(config);

// Monitor detects problems and takes action based on permission level:
// - NotifyOnly: Just alerts (bills due, maintenance needed)
// - LowRisk: Safe actions (add reminders, reorder supplies)
// - MediumRisk: Moderate actions (adjust thermostat, schedule services)
// - HighAutonomy: Full automation (pay bills, control devices)

monitor.start().await?;

6. RAG-Enhanced Agent

Agent with access to a knowledge base:

use chasm::agency::{AgentBuilder, KnowledgeBase, VectorStore, EmbeddingModel};

// Create knowledge base from documents
let mut kb = KnowledgeBase::new();
kb.add_documents_from_directory("./docs").await?;

// Vector store for semantic search
let store = VectorStore::new(VectorStoreConfig {
    embedding_model: EmbeddingModel::TextEmbedding3Small,
    similarity_metric: SimilarityMetric::Cosine,
    ..Default::default()
});

let expert = AgentBuilder::new("domain-expert")
    .instruction("Answer questions using the provided knowledge base. 
                  Always cite sources.")
    .knowledge_base(kb)
    .vector_store(store)
    .build();

let result = runtime.run(&expert, "What is our refund policy?").await?;

7. Multimodal Vision Agent (VLM)

Agent that can understand images:

use chasm::agency::{AgentBuilder, MultimodalMessage, ImageContent, ModelCategory};

let vision_agent = AgentBuilder::new("vision-analyst")
    .model("gemini-2.0-flash")  // VLM model
    .instruction("Analyze images and provide detailed descriptions.")
    .modality(ModelCategory::VLM)
    .build();

// Send image with text
let message = MultimodalMessage::new()
    .text("What's in this image?")
    .image(ImageContent::from_file("screenshot.png")?);

let result = runtime.run(&vision_agent, message).await?;

8. Distributed Task Monitoring

Track agent tasks across multiple machines:

use chasm::agency::{RemoteMonitor, RemoteTask, TaskPriority};

let monitor = RemoteMonitor::new(RemoteMonitorConfig {
    heartbeat_interval: Duration::from_secs(30),
    ..Default::default()
});

// Register remote nodes
monitor.register_node("gpu-server-1", "192.168.1.100:8080").await?;
monitor.register_node("gpu-server-2", "192.168.1.101:8080").await?;

// Submit task to best available node
let task = RemoteTask::builder()
    .title("Train classification model")
    .agent("ml-trainer")
    .priority(TaskPriority::High)
    .build();

let task_id = monitor.submit_task(task).await?;

// Stream progress updates
let mut events = monitor.subscribe_task(task_id);
while let Some(event) = events.recv().await {
    println!("Progress: {}% - {}", event.progress * 100.0, event.message);
}

---

🔌 Agency REST API

The API server provides full CRUD operations for agents:

chasm api serve --port 3000

Endpoints

Method	Endpoint	Description
GET	/api/v1/agents	List all agents
POST	/api/v1/agents	Create an agent
GET	/api/v1/agents/{id}	Get agent details
PUT	/api/v1/agents/{id}	Update an agent
DELETE	/api/v1/agents/{id}	Delete an agent
POST	/api/v1/agents/{id}/clone	Clone an agent
GET	/api/v1/swarms	List all swarms
POST	/api/v1/swarms	Create a swarm
POST	/api/v1/swarms/{id}/start	Start swarm execution
POST	/api/v1/swarms/{id}/pause	Pause swarm
POST	/api/v1/swarms/{id}/resume	Resume swarm
POST	/api/v1/swarms/{id}/stop	Stop swarm

Example: Create an Agent via API

curl -X POST http://localhost:3000/api/v1/agents \

  -H "Content-Type: application/json" \

  -d '{
    "name": "code-assistant",
    "instruction": "You are a helpful coding assistant specializing in Rust.",
    "role": "coder",
    "model": "gemini-2.0-flash",
    "temperature": 0.3,
    "tools": ["file_read", "file_write", "terminal"]
  }'

Example: Run a Swarm

# Create a swarm

curl -X POST http://localhost:3000/api/v1/swarms \

  -H "Content-Type: application/json" \

  -d '{
    "name": "dev-team",
    "coordinator": "tech-lead",
    "workers": ["frontend-dev", "backend-dev", "tester"],
    "description": "Full-stack development team"
  }'


# Start the swarm with a task

curl -X POST http://localhost:3000/api/v1/swarms/{id}/start \

  -H "Content-Type: application/json" \

  -d '{"prompt": "Build a todo app with user authentication"}'

🗃️ Supported Providers

Editor-based

• ✅ GitHub Copilot (VS Code)
• ✅ Cursor
• ✅ Windsurf
• ✅ Continue.dev

Local LLMs

• ✅ Ollama
• ✅ LM Studio
• ✅ GPT4All
• ✅ LocalAI
• ✅ llama.cpp / llamafile

Cloud APIs

• ✅ OpenAI / ChatGPT
• ✅ Anthropic / Claude
• ✅ Google / Gemini
• ✅ Perplexity

📁 Database

Chasm stores all data in a local SQLite database:

Platform	Location
Windows	%LOCALAPPDATA%\csm\csm.db
macOS	~/Library/Application Support/csm/csm.db
Linux	~/.local/share/csm/csm.db

Schema

Workspaces ──< Sessions ──< Messages
                  │
                  ├──< Checkpoints
                  └──< ShareLinks

🛠️ Development

Prerequisites

• Rust 1.75+
• Git

Building

git clone https://github.com/nervosys/chasm.git

cd chasm

cargo build --release

Running tests

cargo test

Running the TUI

cargo run -- tui

📜 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE or http://opensource.org/licenses/MIT)

at your option.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide and Code of Conduct.

🔒 Security

For security issues, please see our Security Policy.

📞 Support

• 📖 Documentation
• 💬 GitHub Discussions
• 🐛 Issue Tracker

---