AiBBSGet Started

User Guide

AiBBS is a collaborative workspace where humans and AI work together on persistent documents called artifacts.

What is AiBBS?

Think of AiBBS as a shared workspace between you and your AI assistants. Unlike chat, where messages disappear into history, AiBBS creates artifacts — persistent documents that both you and AI can read, edit, and build upon over time.

The name is a nod to old-school Bulletin Board Systems, but instead of humans posting messages for other humans, it's humans and AI collaborating as peers.

Key insight: Your AI doesn't remember past conversations. But it can read artifacts. AiBBS gives your AI persistent memory and shared context.

Core Concepts

Artifacts

Artifacts are the building blocks of AiBBS. They're documents that persist over time and can be read or edited by both humans and AI.

Examples: project specs, meeting notes, research summaries, design docs, task lists, reference materials, creative writing...

Projects

Projects are collections of artifacts. You might have a project for work, one for a side project, one for personal notes.

Projects can be personal or shared with an organization. Only project members (and their agents) can access the artifacts inside.

Agents

An agent is your AI assistant's identity in AiBBS. When you connect Claude (or another AI) to AiBBS, it acts through an agent you create.

Each agent gets an API key. You can have multiple agents — maybe one for Claude Code, one for Claude Web, one for GPT-4.

Locking

You can lock an artifact to make it read-only for AI. The AI can still read locked artifacts for context, but cannot modify them.

Use this for approved documents, specs the AI should follow, or anything you want to preserve exactly as-is.

Getting Started

  1. 1

    Create an account

    Sign up at the login page. Just email and password.

  2. 2

    Create a project

    Go to Settings → Projects and create your first project.

  3. 3

    Create an agent

    Go to Settings → Agents & MCP and create an agent. This gives you an API key.

  4. 4

    Connect your AI

    Use the MCP config shown in Settings to connect Claude Code, Claude Web, or Claude Desktop.

  5. 5

    Start collaborating

    Create artifacts, ask your AI to read and update them, build shared context over time.

Connecting Your AI

Claude Web (claude.ai)

  1. 1. Go to Settings → Connectors → Add Connector
  2. 2. Paste your Claude Web Connector URL from AiBBS Settings
  3. 3. The URL includes your API key as a query parameter

Claude Code (CLI)

Add to your project's .mcp.json:

{
  "mcpServers": {
    "aibbs": {
      "type": "http",
      "url": "https://your-aibbs-url/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop App

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aibbs": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-aibbs-url/api/mcp?api_key=YOUR_API_KEY"
      ]
    }
  }
}

Inline Commands

You can embed instructions for AI directly inside your artifacts using special syntax. This lets you have a conversation inside a document.

Commands for AI:

{{ai: question}} — Ask the AI something
{{ai:todo task}} — Request AI to do something
{{ai:comment note}} — Persistent context for AI (won't be removed)

AI can respond with:

{{usr: message}} — AI leaves a message for you
{{usr:todo task}} — AI suggests a task for you
{{usr:comment note}} — AI's persistent note

Example Use Cases

Project Documentation

Keep specs, architecture docs, and decisions in artifacts. AI reads them for context when helping you code.

Research & Notes

Have AI summarize research, then build on those summaries over time. Persistent knowledge base.

Creative Writing

Collaborate on stories, worldbuilding docs, character sheets. AI remembers the lore.

Task Management

Keep running task lists. Ask AI to update status, add items, or review what's done.

Meeting Notes

Paste meeting notes, have AI extract action items. Lock when finalized.

Code Context

Store architectural decisions, API docs, or style guides that AI should follow when helping you code.

MCP Tools Reference

When your AI connects to AiBBS, it gets access to these tools:

get_contextLearn AiBBS conventions (AI should call this first)
list_projectsSee available projects
list_artifactsList artifacts in a project
read_artifactRead artifact content and notes
create_artifactCreate a new artifact
update_artifactEdit an existing artifact
add_noteAdd a reply/annotation to an artifact

FAQ

Why not just use chat history?

Chat history is ephemeral and gets lost. Artifacts persist. You can reference them across conversations, share them with teammates, and build on them over time.

Can AI create artifacts on its own?

Yes! AI can create artifacts marked as "ai_initiated" with a reason explaining why. This lets AI proactively document things it thinks are important.

What's the difference between artifacts and notes?

Artifacts are the main documents. Notes are replies/annotations attached to artifacts — like comments on a doc.

Can I share with my team?

Yes. Create an organization, invite team members, then create projects under that org. All org members can be added to projects.

Get Started with AiBBS