Duet

Human + Agent Collaborative Notes

The note-taking app with a built-in MCP server.
Your AI agents collaborate alongside you - with full attribution and permission control.

---

What is Duet?

Duet is a self-hosted note-taking app designed for collaborative use between humans and AI agents. It includes a built-in MCP server so any compatible AI agent (Claude, Cursor, VS Code, etc.) can read, write, and manage notes alongside you - with every edit tracked by author.

Features

• MCP Server - 12 tools out of the box. Any MCP-compatible agent connects in seconds
• Author Attribution - every note and edit tracks who wrote it (human vs agent)
• Permission Boundaries - agents can read, write, and archive - but never delete
• Real-time Updates - WebSocket push via PostgreSQL LISTEN/NOTIFY
• Rich Text Editor - headings, lists, checklists, code blocks, images (Tiptap)
• Full-text Search - PostgreSQL tsvector powered instant search
• Version History - every edit tracked with full diff timeline
• CLI - pipe-friendly command line with JSON output
• REST API - complete API for any integration
• Google Calendar Sync - todos with due dates sync to your calendar
• Tags & Todos - organize notes with tags, manage todos with priorities

Quick Start

Docker (recommended)

git clone https://github.com/emreparker/duet.git
cd duet
cp .env.example .env
# Edit .env with your SESSION_SECRET
docker compose up -d

Visit http://localhost:7777 and set your password.

Manual

git clone https://github.com/emreparker/duet.git
cd duet
pnpm install
createdb duet_dev
cp .env.example .env
pnpm db:migrate
pnpm dev

Connect Your Agent

1. Go to Agents in the sidebar and register a new agent
2. Copy the API key
3. Add to your MCP client config:

{
  "mcpServers": {
    "duet": {
      "command": "npx",
      "args": ["@noteduet/mcp-server"],
      "env": {
        "DUET_DATABASE_URL": "postgresql://localhost:5432/duet_dev",
        "DUET_AGENT_NAME": "claude",
        "DUET_API_KEY": "duet_your_key_here"
      }
    }
  }
}

Your agent now has access to 12 tools: create_note, read_note, update_note, list_notes, search_notes, archive_note, get_note_history, create_todo, list_todos, update_todo, complete_todo, and get_activity_feed.

CLI

npm install -g @noteduet/cli

# Create a note
duet note add "Meeting notes from standup" --title "Standup 2025-03-19"

# List notes
duet note list

# Search
duet note search "deployment"

# Manage todos
duet todo add "Review PR" --priority high --due 2025-03-20
duet todo list
duet todo done <id>

# View activity feed
duet activity

Duet Cloud

A hosted version at noteduet.com is coming soon. Sign up for early access on the website.

Documentation

Full documentation is available at noteduet.com/docs:

• Self-hosted Setup
• MCP Setup
• MCP Tools Reference
• CLI Reference
• REST API Reference
• Google Calendar Sync
• Docker Deployment
• Fly.io Deployment

Tech Stack

Layer	Technology
API	Hono
Database	PostgreSQL + Drizzle ORM
Frontend	Next.js
Editor	Tiptap
MCP	@modelcontextprotocol/sdk
CLI	Commander
Language	TypeScript (everywhere)

Architecture

duet/
  packages/
    core/          ← Hono API + Drizzle ORM + business logic
    mcp-server/    ← MCP server (imports core directly, no HTTP hop)
    cli/           ← CLI tool (imports core directly)
  apps/
    web/           ← Next.js web app

Core is the single source of truth. MCP server and CLI import it as a library - no HTTP overhead.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

AGPLv3