CODERSBUD
Sign in Sign up
Get Started

Welcome to CodersBud Docs

CodersBud is a terminal-first collaboration app. Use the website for account access and CLI token generation, then do the actual work in the TUI.

Website

Register, log in, and generate CLI tokens from the dashboard. The browser is not the main workspace.

TUI

Chat, DMs, presence, read status, attachments, code snippets, and keyboard-first navigation live in the terminal client.

Git Flows

Send one-off repo transfers or create persistent shared repos with clone, push, history, and review support.

Feed

Publish tweets, posts, and articles with tags, likes, views, threaded comments, and lightweight editing from the TUI.

Overview

Overview

CodersBud has two separate surfaces by design. The website is the account and token entrypoint. The terminal UI is the main product.

Website Responsibilities

  • Create an account and log in.
  • Open the dashboard and generate CLI tokens.
  • Keep web auth separate from terminal auth.

TUI Responsibilities

  • Realtime chat in DMs and group channels.
  • Presence, read status, reply/edit/delete flows, and file attachments.
  • Feed browsing, posting, commenting, and lightweight moderation of your own content.

One-Off Repo Transfers

  • Bundle a clean local Git repo and send it to other members in the active chat.
  • Recipients can accept, reject, and apply it locally.
  • Transfers expire automatically after 24 hours.

Persistent Shared Repos

  • Initialize a shared repo in a channel, clone it locally, push new commits, and review change history.
  • Repo review includes additions, deletions, file counts, and file-level patches.
  • Clone and push use authenticated Git HTTP endpoints backed by the server.
Install

Quick Start

Three steps to go from zero to a running terminal app.

1. Install the CLI

curl -fsSL codersbud.dev/install | sh

Works on macOS and Linux (amd64 / arm64). The installer drops a codersbud binary into ~/.local/bin. If that folder isn't on your PATH the installer prints the line to add to your shell profile.

2. Register and generate a CLI token

  1. Open codersbud.dev/register and create an account.
  2. Open the dashboard.
  3. Click Generate CLI token and copy the value.

3. Authenticate and launch

codersbud auth <token>
codersbud

You're in. Ctrl+C exits the TUI.

Auth

Authentication

Web sign-in and terminal sign-in are separate. The website issues a CLI token; the terminal saves it locally.

  1. Register or log in at codersbud.dev.
  2. Open the dashboard and generate a CLI token.
  3. Run codersbud auth <token> in your shell.
  4. Run codersbud to launch the TUI.
  5. Run codersbud logout to clear the saved session.

Sessions last 7 days. If your token expires, generate a new one from the dashboard and re-run codersbud auth <token>.

Chat

Chat

Channels

  • The sidebar shows DMs and group channels.
  • The TUI directly supports creating DMs by email with Ctrl+N or /dm <email>.
  • The active channel drives message history, transfers, shared repos, and read status.

Messages

  • Messages support replies, edits, soft deletion, fenced code blocks, and attachments.
  • Read cursors are tracked per channel.
  • DM partners surface online/offline presence in realtime.
Copy flows: select a message with Ctrl+S and press c.
CLI

Slash Commands

Command Purpose Notes
/dm <email> Create or open a DM with another user. If no email is provided, the TUI opens the DM prompt.
/transfer Start a one-off repo transfer. You can also run /transfer <repo-path> directly.
/repo-init <repo-path> Create a persistent shared repo in the active channel. The repo must be clean and on a named branch.
/repos List shared repos in the current channel. IDs are shown as short prefixes such as id:1234abcd.
/repo-clone <repo-id> <parent-dir> Clone a shared repo via the authenticated Git remote. If the target folder already exists, it is renamed to a timestamped backup before cloning.
/repo-push <repo-id> <repo-path> Push new local commits to the shared repo. The local branch must match the shared repo default branch.
/repo-delete <repo-id> Delete a shared repo from the current channel. Use with care. The repo is removed from the shared channel state.
/repo-history <repo-id> List shared repo changes with commit and file stats. Use this before opening a detailed review.
/repo-review <repo-id> <change-id> Open one repo change for file-by-file review. Pulls file metadata and stored patches for that change.
/repo-next / /repo-prev Move between files in the active review. Only works after /repo-review.
/attach <path> Upload one or more files or images. The command prompt also accepts dragged file paths.
/pending List pending repo transfers for the current user. Shows short transfer IDs and repo/branch names.
/accept Accept a transfer and apply it locally. Can be interactive, or /accept <transfer-id> <parent-dir>.
/reject Reject a pending transfer. Can be interactive, or /reject <transfer-id>.
Transfers

One-Off Repo Transfers

  1. Open a DM or group channel.
  2. Run /transfer and provide the absolute repo path, or pass the path directly.
  3. The client validates that the directory is a Git repo, has no uncommitted changes, and is not in detached HEAD.
  4. The client creates a Git bundle and uploads it to the server.
  5. Recipients use /pending, /accept, or /reject.
  6. On accept, the bundle is cloned into the chosen parent directory and the apply result is sent back to the server.

Transfer Rules

  • Only DM and group channels support transfers.
  • Recipients are all other channel members except the sender.
  • Maximum bundle size is 200 MB.
  • Transfers expire after 24 hours.

Status Model

  • pending
  • accepted
  • rejected
  • applied
  • failed
  • expired
Git

Shared Repos

Shared repos are persistent channel-level repositories backed by the server. They are different from one-off transfers.

  1. Initialize a shared repo from a clean local repo with /repo-init <repo-path>.
  2. List repos in the channel with /repos.
  3. Clone locally with /repo-clone <repo-id> <parent-dir>.
  4. Push new commits with /repo-push <repo-id> <repo-path>.
  5. Inspect change history with /repo-history <repo-id>.
  6. Open a review with /repo-review <repo-id> <change-id>, then navigate files with /repo-next and /repo-prev.

Behavior

  • Shared repo names must be unique per channel.
  • Only DM and group channels support shared repos.
  • Clone and push happen through authenticated Git HTTP endpoints exposed by the server.
  • Each push stores additions, deletions, file count, and file-level patch data for later review.

Push Constraints

  • The pushed branch must match the repo default branch.
  • A base commit is required and must still match the shared repo head.
  • If the remote moved, the push is rejected and you must pull the latest snapshot first.
  • If there are no new commits, push is rejected as nothing to push.
Clone safety: shared repo clone follows the same backup rule as transfers. If the target repo folder already exists, it is renamed to a timestamped .backup-* folder before cloning.
Feed

Feed

Post Types

  • tweet up to 280 characters.
  • post up to 2000 characters.
  • article up to 20000 characters and requires a title.

Tags

ai backend cloud coding data devops engineering frontend ml security swe

Post Actions

  • Create, edit, and delete your own posts.
  • Like posts and record views.
  • Open a post in detail view for discussion.

Comments

  • Comments can be up to 1000 characters.
  • Replies are limited to one level deep and can only target top-level comments.
  • You can edit, delete, and like your own comment content from the detail view.
Files

Files And Code Snippets

Attachments

  • Use /attach <path> to send files or images.
  • Dragged file paths are also supported by the attachment flow.
  • The TUI downloads attachments in the background and caches them locally.
  • Default client download location is ~/Downloads/codersbud.

Code Blocks

  • Fenced code blocks are syntax highlighted in chat and feed detail views.
  • Select a message and press o to open its first fenced code block in VS Code.
  • The TUI writes the code block to a temporary file and calls code --goto.
Notes

Limits

  • Attachments are capped at 50 MB per file.
  • Repo transfers and shared repos both enforce a 200 MB bundle limit.
  • The website handles sign-up, login, the dashboard, and public snippet links. The full collaboration experience lives in the TUI.
  • Shared repo and transfer flows need git available in your shell.
Troubleshooting

Troubleshooting

codersbud: command not found

Re-run the installer (curl -fsSL codersbud.dev/install | sh) and follow its instructions to add ~/.local/bin to your PATH.

not authenticated

Generate a fresh token from the dashboard and run codersbud auth <token>.

saved session is invalid

The token expired (sessions last 7 days). Generate a new CLI token from the dashboard and authenticate again.

Shared repo push conflict

The remote moved since your last sync. Re-clone or refresh from the latest shared repo snapshot, then retry the push.

Code block did not open in VS Code

Install VS Code and make sure the code command is available in your shell PATH.