Continuity Documentation

Continuity

File-based messaging for AI development workflows.

Continuity lets you send messages to AI assistants when they’re not running and check responses without burning tokens. Think email for AI collaboration - conversations persist across sessions and context switches.

Simple, project-based paradigm familiar to developers. Initialize Continuity in your project root and start sending messages. Track messages with git, upload them to the cloud. But only if you want.

The goal is simple: stop losing ideas when AI sessions end and stop wasting time reconstructing context.

The Problem

Ideas get lost during AI context switches.

You’re working with an AI assistant and have an idea for the next feature. But the AI is busy fixing a bug and will hit its context limit soon. By the time you start a new session, the idea is gone.

Context reconstruction wastes time.

Every new AI session starts from scratch. You spend the first part of every conversation re-explaining the project, your preferences, and what you were working on.

Multi-day conversations don’t work.

Want to have a thoughtful discussion about architecture that spans several days? Current AI coding agents aren’t built for that. Copy/pasting from Chatbot conversations re-opens the coding feedback loop that agents are meant to close. Continuing old agent sessions only prolongs the inevitable need for context reconstruction.

Complex prompts are more fun to write in your text editor.

Sometimes you need a detailed prompt with examples and context. Writing that in a chat box is clunky, and you can’t save it for later use.

The Solution

Send messages when the AI isn’t running:

# Save your idea for later
continuity send "Remember to escape your strings if you pass text via stdin!"

Check status without using tokens:

# See what the AI wrote back
continuity check

Write complex prompts in your editor:

# Send from file
vim detailed-prompt.md
continuity send --file detailed-prompt.md --title "Architecture Review Request"

# Pipe from commands
grep -n "TODO\|FIXME" src/*.py | continuity send --title "Outstanding TODOs"

Quick Start

# Install
git clone https://github.com/mjrskiles/continuity.git
cd continuity && ./install.sh

# (Recommended but optional) automatically load global settings file
echo 'source ~/.continuityrc' >> ~/.bashrc && source ~/.continuityrc

# Set up in your project
cd /path/to/my-project
continuity init

# Send your first message
continuity send "Hey AI, can you audit this project for code smells as soon as you read this?"

What Makes It Useful

Persistent conversations:

Messages survive AI session restarts and context limits
Switch between different AI models without losing message history
Continue discussions across days or weeks

No interruptions:

Capture ideas without breaking your current flow
No notifications or popups
Check messages on your schedule

Developer workflow:

Familiar commands: init, status,
Plain text files you can grep, diff, and version control
CLI-first design

Core Commands

# Basic workflow
continuity check                            # See new messages (no tokens)
continuity view 1                           # Read message 1
continuity mark 1                           # Mark as read
continuity send "Your message here"         # Send message to AI

# Project setup
continuity init                             # Initialize project
continuity status                           # Check activity

File Structure

Everything is plain text files:

.continuity/
├── agent/mailbox/          # Messages to AI
├── human/mailbox/          # Messages from AI
└── inbox/                  # Drop files here for processing

Searchable: grep -r "API design" .continuity/
Version controllable: Track with git if you want
Portable: Works with any text editor

Usage Examples

Check system and mailbox:

continuity status           # Overview of unread and unprocessed messages
continuity check            # Any new messages for me?

Save ideas quickly:

continuity send "Edge case: what if user uploads empty file?"

Reply to specific messages:

continuity reply 3 "Actually, let's prioritize the performance fixes first."

Send command output:

# Send test results
pytest your_test.py 2>&1 | continuity send --title "Test failures to investigate"

# Send code changes
git diff HEAD~1 | continuity send --title "Please review this change"

Installation

Requirements:

Python 3.8+ (3.12+ recommended)
Linux/macOS/WSL (Windows not supported)
Git (for user detection)

Install

git clone https://github.com/mjrskiles/continuity.git
cd continuity
./install.sh

Verify it works:

continuity --help
continuity status

What the installer does:

Creates isolated Python environment in ~/.local/share/continuity-venv
Installs continuity with dependencies
Sets up shell integration for the continuity command
Configures bash completion
Offers optional ct alias

Set up a project

cd /path/to/your/project
continuity init
continuity status

The ct alias is available if you want a shorter command.

Uninstall

./uninstall.sh

Removes the virtual environment, shell integration, and bash completion.

Configuration

Shell Configuration (.continuityrc)

The installer creates ~/.continuityrc for your customizations:

# Add your custom aliases, functions, and environment variables below

# Example customizations:
alias ct='continuity'
alias cs='continuity status'
export CONTINUITY_EDITOR='code'

# Custom function for quick project check
cstatus() {
    cd "$CONTINUITY_PROJECT_ROOT" && continuity status
}

Your customizations survive reinstalls and updates.

Documentation

Architecture - How it works
CLI Reference - Complete command guide
Style Guide - Code conventions

Development

Continuity uses pyproject.toml for modern Python packaging and tool configuration.

Quick setup:

# Create development virtual environment
python3 -m venv venv-dev

# Install continuity with all development dependencies
venv-dev/bin/pip install -e .[dev]

For the crossing, not the destination