Projects

Projects

Overview

A Project maps 1:1 with a Discord category and defines a shared workspace directory. All rooms (channels) inside a project category share the same workspace — each channel gets its own tmux session and agent instance, but they all see the same files.

Creating a Project

/project create name:my-app dir:/home/user/my-app

This creates:

1. A Discord category named my-app
2. A Project record in the database linking the category to the workspace path

If dir is omitted, defaults to <WORKSPACE_ROOT>/<name>.

You can also set a default permission mode:

/project create name:my-app dir:/home/user/my-app mode:acceptEdits

Auto-Registration

When someone creates a new channel inside a project category (via Discord UI, not /new), the bot automatically registers it as a room using the project's shared workspace.

The bot posts a welcome message confirming the auto-registration.

Using /new Inside a Project

When you run /new from a channel that's inside a project category:

• If you don't specify path, the room automatically uses the project's workspace
• If you do specify path, it overrides the project workspace

/new name:fix-auth              # uses project workspace
/new name:sandbox path:/tmp/test  # overrides with custom path

Commands

Command	Description
/project create name:<name> [dir:<path>] [mode:<mode>]	Create a project category + shared workspace
/project list	List all projects in this guild
/project delete force:True [delete_rooms:True]	Delete this project
/project info	Show project info for the current category

Workspace Sharing

All rooms in a project share the same filesystem directory. This means:

• Multiple Claude/agent instances can see and edit the same files
• Changes made in one room are visible in all other rooms
• Attachments uploaded in any room land in the shared .uploads/ folder

Resume Markers

To avoid resume collisions in shared workspaces, each room gets its own marker file:

<workspace>/.claude-tmux-discord/<channelId>/started

This allows each room to independently track whether it should resume (--continue) or start fresh.

Deleting a Project

/project delete force:True                  # remove project record only
/project delete force:True delete_rooms:True  # also unregister all rooms

Note: /delete wipe:True is blocked for rooms that belong to a project, to protect the shared workspace from accidental deletion.

Database Schema

model Project {
  categoryId   String   @id @map("category_id")
  guildId      String   @map("guild_id")
  name         String
  workspaceDir String   @map("workspace_dir")
  defaultMode  String   @default("bypassPermissions")
  createdAt    DateTime @default(now())
  createdBy    String
  rooms        Room[]
}

The Room model has an optional projectId foreign key linking it to a project.