Documentation

codecast.sh

Inbox

Every agent, grouped by what it needs from you

Conversations

Watch and steer a session live

Command palette

Jump to anything with one key

Changes

What shipped, as a story

Tasks & plans

One board for people and agents

Mobile

Answer an agent from your phone

Getting Started

Two minutes, three steps. Codecast reads the sessions your agents already keep on your computer, so nothing changes about how you run them.

The App

The same app runs at codecast.sh, as a native Mac app and on iPhone. Navigation sits on the left, the page you are on in the middle, and the inbox of your sessions on the right, so whatever you open, the agents that need you stay in view.

Inbox

Every session you run, on any computer, gets a card in the inbox: its title, a one-line summary of where it stands, the last thing you said to it, its project and how long ago it moved. Cards are grouped by what they need from you:

The chips across the top filter the inbox by label or project. Click a card to open its conversation. Stash a card once you are done with it and the inbox moves you to the next one.

Conversations

A conversation is the agent's whole session, live. Its replies render as formatted text, and the work between them folds into one line (“ran 3 commands”, “read 2 files”) that opens on a click. Background commands, monitors and scheduled wakeups show where they run and what they are waiting on.

The header carries the agent, model, branch and the task, plan or workflow the session is working on. The files-changed pill opens the diff. Type into the composer to steer the agent mid-run; when it is waiting on you, a suggested reply appears that Tab accepts.

codecast.sh

Command Palette

Press Cmd+K to open a Linear-style command palette that searches across sessions, tasks, plans, docs, and built-in actions. Results are ranked by recency and relevance, with separate groups for each entity type.

The palette supports quick actions directly on search results: pin, stash, defer, kill, or rename sessions without leaving the palette. Type a slash prefix to filter by entity type (/task, /plan, /doc) or use it as a launcher for built-in navigation (inbox, tasks, plans, docs, settings).

codecast.sh

Changes

Changes is the story of what shipped. It opens with a summary of the week, then groups each day's commits into a handful of headlines with their size and the releases that carried them. The strip at the top shows which version of each part is live right now.

codecast.sh

Tasks & Plans

Tasks are the work, whoever does it: you, a teammate or an agent. The board groups them by status and shows who holds each one, its priority and how long it has been open. Filters live in the URL, so a view is a link you can share or pin to the sidebar.

codecast.sh

A plan holds a larger goal across many sessions: its tasks, a progress bar, the sessions bound to it, and a timeline of the decisions and findings agents posted along the way.

codecast.sh

Documents

A collaborative document editor for specs, designs, investigations, handoffs, and notes. Documents are TipTap-powered with rich formatting: headings, lists, code blocks, and images.

The key feature is entity mentions -- type @ to reference sessions, tasks, plans, or other docs inline. Mentions are resolved and rendered as rich links with status badges. Slash commands (/) provide quick formatting and entity insertion.

Documents can be created from the web UI, CLI (cast doc create), or promoted from plan bodies. Types include note, plan, design, spec, investigation, and handoff. All documents are searchable via the command palette and CLI.

Chat & Calls

Teams talk in channels and direct messages next to their sessions, and agents post there too: a session can announce what it shipped, and the team's own agent answers when someone mentions it. Channels can mirror Slack. Huddles are transcribed with who said what, and each call ends with a summary and its action items.

codecast.sh

Keyboard Shortcuts

The inbox is designed for keyboard-first orchestration. Navigate, triage, and respond to agents without leaving the keyboard.

Download

The desktop app provides native macOS integration with system notifications, menu bar access, and a dedicated window. Everything in the web app works identically in the desktop app.

Mobile App

Your AI coding sessions, always in your pocket. The iOS app gives you full access to your sessions, agents, and team activity from anywhere.

Features

Live session streaming

Watch your agents work in real-time with push notifications when they need input

Send messages

Send prompts and messages to running agents directly from your phone

Review diffs

Review code changes and approve permissions remotely

Full search

Search your entire session history on the go

Download

Teams

Setup

Create a team from Settings > Team: name it, pick the repositories it works in, and invite your first teammate. Teammates join from their invite or with the team's invite code. Once you are in a team, the workspace switcher at the top left moves you between it and your personal workspace, and the team's people, channels and shared sessions show up in the sidebar.

The same from a terminal:

# Create a team
$ cast teams create "acme-eng" --icon "🚀"
# Invite members
$ cast teams invite [email protected] -r admin
$ cast teams invite [email protected]
# Join with invite code
$ cast teams join abc123
# See and change what syncs and what each team sees
$ cast sharing
$ cast sharing share ~/src/app --team acme-eng --dry-run

Sharing & Privacy

Sessions are private by default. Sharing is controlled at three levels:

cast sharing reads and changes all of it without prompts, so an agent can do it for you: the Sync & Privacy settings page has a Decide with an agent button that starts one, briefed to look through your folders, recommend a setting for each, and change nothing until you agree.

Integrations

Supported Tools

GitHub

Install the GitHub app to link PRs with sessions, process webhook events, and fire agent triggers on repository activity.

Configure at Settings > Integrations > GitHub App on the web dashboard. Once installed, PRs are automatically linked to the sessions that created them, and you can set up triggers that fire on repository events.

Guides

One feature at a time: what it does for you, how to turn it on, what to ask your agents, and what you will see when they use it.

Agent Memory

Every AI coding session starts from scratch. Agent memory changes that -- your agent can search all past sessions, recall decisions, and understand context from work done days or weeks ago. Memory works across all tools: a Claude Code session can recall what you built in Cursor.

Setup

Run cast memory to install the memory component into your project's CLAUDE.md. This gives your agent instructions on how to use codecast for context retrieval.

## Memory
You have access to past sessions via cast CLI.
Search proactively when starting new tasks.
# Search & Browse
cast search "auth" -s 7d          # keyword search
cast context "stripe integration"  # pre-work intelligence
cast ask "why did we use Convex?"  # natural language query
# Recall
cast handoff                       # context transfer doc
cast decisions list                # architectural decisions
cast blame src/auth.ts             # git blame, lines resolve to sessions

Commands

How It Works

Codecast builds a hybrid search index over your sessions -- combining keyword matching with semantic embeddings. When your agent calls cast search or cast ask, it queries this index and returns relevant messages with full context. The agent sees the original conversation fragments, not summaries, so it gets precise, actionable information.

Search & Browse

Find any session, message, or file change across your entire history. Supports exact phrases, time range filters, team member filters, and context lines around matches.

Search

# Basic search
$ cast search "auth bug"
# Exact phrase (quotes = phrase match)
$ cast search "token refresh logic"
# Time range
$ cast search auth -s 7d
$ cast search auth -s 2025-01-01 -e 2025-02-01
# Global (all projects)
$ cast search auth -g
# By team member
$ cast search auth -m sarah
# User messages only
$ cast search auth -u
# With context lines
$ cast search "webhook" -C 3
# Keyword-only or semantic-only
$ cast search auth --keyword
$ cast search "how does auth work" --semantic

Feed & List

Browse recent sessions chronologically.

# Recent sessions feed
$ cast feed
# Global feed (all projects)
$ cast feed -g
# Filter by keyword
$ cast feed -q "payments"
# Filter by team member
$ cast feed -m alex
# Paginated
$ cast feed -n 20 -p 2

Read Messages

Read specific messages from any session by ID and range.

# Read full conversation
$ cast read abc123
# Read messages 10 through 20
$ cast read abc123 10:20
# Read from message 50 onward
$ cast read abc123 50:

Session Analysis

Understand what happened in any session -- files changed, commits made, tools used. Generate summaries and handoff documents for continuity between sessions.

Diff & Summary

# Files changed, commits, tools used in a session
$ cast diff abc123
# Aggregate today's changes across all sessions
$ cast diff --today
# Generate session summary
$ cast summary abc123
# Summarize today's work
$ cast summary --today

Context & Handoff

cast context gathers relevant prior work before you start something new.cast handoff generates a context transfer document for session continuity.

# Pre-work intelligence
$ cast context "add stripe payments"
  Found 3 relevant sessions:
  - Payment webhook debugging (2d ago)
  - Stripe SDK integration (1w ago)
  - Billing page UI (1w ago)
# Generate handoff doc
$ cast handoff
  Handoff document generated.
  Goal: Implement dark mode across settings
  Approach: CSS variables with system preference sync
  Status: Tests passing, 2 edge cases remaining
  Next: Fix mobile viewport handling

Blame & Similar

cast blame is a drop-in git blame whose author column is the codecast session -- and person -- that wrote each line. Output matches git blame exactly, so anything that parses it keeps working. See Editor Integration to wire it into your editor.

# Line-level blame: each line resolves to the session that wrote it
$ cast blame src/auth/callback.ts
  aef1990f2 (jx74qbm Samvit Agent prompt guardrails  2026-05-13  1) export ...
# Just one line
$ cast blame src/auth/callback.ts:42
# Session log for a file -- which sessions shaped it, newest first
$ cast blame --log src/auth/callback.ts
# Find sessions with related files
$ cast similar --file src/api.ts

A line resolves when it was committed (or written) through a synced session you can see; other lines fall back to the normal git author. It works across machines and teammates -- attribution rides on the commit, not the file's path on disk.

Editor Integration

Session Blame

Bring session blame into your editor: hover a line to see which session (and teammate) wrote it, and jump straight to that conversation -- anchored to the exact edit. Two integrations ship today; both are thin clients over the cast CLI, so they share one source of truth.

Vim / Neovim (fugitive)

If you use vim-fugitive, one command wires it up. It installs a tiny git shim that routes fugitive's blame through codecast and writes the vim glue:

$ cast blame --install-fugitive
# then add to your vimrc / init.vim:
source ~/.codecast/fugitive.vim

Now in any git repo:

VS Code / Cursor

Two options. The extension gives inline blame on the current line plus commands to open the conversation and session log. The terminal tasks need no extension -- they run cast from the integrated terminal. Both require the CLI installed and authenticated (cast auth).

Option 1 — Extension

# Install the downloaded extension (works in VS Code and Cursor)
$ code --install-extension ~/Downloads/codecast-blame.vsix
# or Cursor:  cursor --install-extension ~/Downloads/codecast-blame.vsix
# If 'cast' isn't on your editor's PATH, set codecast.cliPath
# (Settings -> Codecast -> Cli Path) to the output of:  which cast

Option 2 — Terminal tasks (no extension)

Add a task and keybinding that run cast on the current file and line -- works identically in VS Code and Cursor.

{
  "version": "2.0.0",
  "tasks": [
    { "label": "cast: open session for line", "type": "shell",
      "command": "cast blame ${file}:${lineNumber} --open" },
    { "label": "cast: session log", "type": "shell",
      "command": "cast blame --log ${file}",
      "presentation": { "reveal": "always", "panel": "shared" } }
  ]
}

{ "key": "cmd+alt+b", "command": "workbench.action.tasks.runTask",
  "args": "cast: open session for line" },
{ "key": "cmd+alt+l", "command": "workbench.action.tasks.runTask",
  "args": "cast: session log" }

Plans

Overview

Plans are multi-session features. Create a plan, define goals and acceptance criteria, then bind sessions to it as you work. Each session logs decisions and discoveries that other sessions can reference -- so parallel agents stay coordinated.

Commands

# Create a plan
$ cast plan create "Add payments" -g "Stripe integration with subscriptions" -a "Checkout works, webhooks verified, tests pass"
# List plans
$ cast plan ls --active
$ cast plan ls --draft
# Show plan details (tasks, decisions, progress)
$ cast plan show ct-a1b2
# Bind current session to a plan
$ cast plan bind ct-a1b2
# Add comments (progress, decisions, discoveries, references)
$ cast plan comment ct-a1b2 "deployed to staging"
$ cast plan comment ct-a1b2 "Use Stripe Checkout" -d -r "Simpler than custom flow, handles SCA"
$ cast plan comment ct-a1b2 "Stripe webhooks need idempotency keys" -f
$ cast plan comment ct-a1b2 "API schema" --ref docs/api.md
# Lifecycle
$ cast plan activate ct-a1b2
$ cast plan pause ct-a1b2
$ cast plan done ct-a1b2

Workflow

A typical plan lifecycle: create in draft, move to active when work begins, bind sessions as agents work on it, add comments along the way (decisions, discoveries, references), and mark done when acceptance criteria are met. Plans are visible in the web dashboard with progress bars, linked sessions, and a unified comment timeline.

Orchestration

Orchestration runs plan tasks in parallel waves across multiple agents. When you call cast plan orchestrate <id>, codecast decomposes the plan into dependency-aware waves and spins up agent sessions for each task -- each with full plan context, decisions, and relevant prior sessions.

# Decompose plan into tasks (if not done already)
$ cast plan decompose ct-a1b2
# Orchestrate: run tasks in parallel waves
$ cast plan orchestrate ct-a1b2
  Wave 1: starting 3 tasks in parallel...
    ct-t1 "Database schema migration" → claude session abc
    ct-t2 "API endpoint stubs" → codex session def
    ct-t3 "Test fixtures" → claude session ghi
  Wave 1: 3/3 complete
  Wave 2: starting 2 tasks (depended on wave 1)...
    ct-t4 "Business logic" → claude session jkl
    ct-t5 "Integration tests" → codex session mno
  Wave 2: 2/2 complete
  Plan ct-a1b2 complete. 5 tasks done.

Failed tasks retry automatically with escalation logging. If a task fails multiple times, it's marked as blocked and orchestration continues with remaining tasks. You can monitor progress from the web dashboard or CLI.

Tasks

Overview

Tasks are work items -- features, bugs, chores. They can belong to a plan or stand alone. Tasks have priorities, dependencies, and a status workflow: draft → open → in_progress → in_review → done.

Commands

# Create a task
$ cast task create "Add password reset" -t feature -p high --plan ct-a1b2
# List tasks
$ cast task ls --status open -p high
$ cast task ready                  # unblocked tasks ready to work
# Work on a task
$ cast task start ct-x1y2          # marks in_progress
$ cast task comment ct-x1y2 "Implemented reset flow" -t progress
$ cast task done ct-x1y2           # marks done
# Dependencies
$ cast task create "Email templates" --blocked-by ct-x1y2

Auto-Mining & Triage

Codecast automatically mines tasks from your agent sessions. As agents work, they generate insights -- when an insight looks like a work item, it's extracted as a suggested task with a confidence score.

Suggested tasks appear in a triage queue on the web dashboard. You can accept, dismiss, or edit them before promoting to your task backlog. Accepted tasks can be bound to plans, assigned priorities, and given labels. Dismissed tasks are hidden but recoverable.

The triage system has three status categories: active (accepted into your backlog), suggested (mined but not yet triaged), and dismissed (rejected). Filter toggles in the toolbar let you switch between these views.

Workflows

Visual workflow definitions with node-based execution. Define multi-step pipelines that combine agent tasks, shell commands, prompts, human approvals, and conditional logic. Workflows run with live progress tracking, and each node gets its own tmux session streamed to the dashboard.

Node Types

Execution

Workflows are attached to plans and executed from the CLI or web dashboard. Each run creates a primary conversation visible in the inbox, and individual node sessions appear as sub-sessions.

# Attach a workflow definition to a plan
$ cast plan set-workflow ct-a1b2 workflow.yaml
# Execute the workflow
$ cast workflow run ct-a1b2
  Starting workflow for plan "Auth Overhaul"...
  [1/5] agent: "Design API schema" → session abc
  [2/5] command: npm test → exit 0
  [3/5] human_gate: "Review the schema design"
        Waiting for human input...

Human gates pause the workflow and notify you (via push notification on mobile or desktop). Reply through the regular message composer to continue. The workflow resumes with your input passed to the next node.

Triggers

Overview

Set triggers — autonomous agent runs that fire without your involvement. One-shot triggers fire after a delay, recurring triggers fire on an interval, and event triggers fire in response to GitHub webhooks.

A trigger created inside a session binds to it: each run continues that session as a new turn, with its full history. Pass --spawn to start a fresh session per run instead — no history, just your prompt, with a link back to the trigger at the top of each run's conversation.

Commands

# One-shot: check CI in 30 minutes (continues the current session)
$ cast trigger add "Check if CI is green on main" --in 30m
# Recurring, fresh session per run, linked back to the trigger
$ cast trigger add "Review open PRs and summarize" --every 4h --spawn
# Manage triggers
$ cast trigger ls                 # list active
$ cast trigger ls --all           # include completed/failed
$ cast trigger run ct-s1          # fire immediately
$ cast trigger pause ct-s1        # pause
$ cast trigger cancel ct-s1       # cancel
$ cast trigger log ct-s1          # view last run output

Event Triggers

With the GitHub integration installed, triggers can fire on repository events.

# Respond to new PR comments
$ cast trigger add "Respond to PR review comments" --on pr_comment
# Run on new PRs
$ cast trigger add "Review PR for security issues" --on pr_opened
# Run after merge
$ cast trigger add "Verify deployment after merge" --on pr_merged
# Run on push to main
$ cast trigger add "Check for broken tests" --on push

Knowledge

Decisions

Track architectural decisions with rationale. Searchable by your agent and your team.

# Record a decision
$ cast decisions add "Use Convex for backend" --reason "Real-time subscriptions, no WebSocket infra needed" --tags "backend,database"
# List recent decisions
$ cast decisions
# Search decisions
$ cast decisions --search "database"
# Filter by project
$ cast decisions --project /Users/me/src/app
# Delete
$ cast decisions delete ct-d1

Bookmarks

# Bookmark a specific message
$ cast bookmark abc123 42 --name "auth-pattern" --note "Good pattern for OAuth callback"
# List bookmarks
$ cast bookmark --list
# Delete
$ cast bookmark --delete auth-pattern

Background Sync

Authentication

Authenticate via browser OAuth. This links your machine to your codecast account.

$ cast auth
Opening browser for authentication...
Authenticated as [email protected]

Alternatively, generate a setup token on the web dashboard at Settings > CLI and run cast login <token>.

The Daemon

The daemon watches your local session files and syncs them in real-time. It runs quietly in the background with no impact on your workflow.

$ cast start
Daemon started (pid 42891)
Watching for sessions...
$ cast status
Daemon: running (pid 42891)
Sessions: 847 synced, 0 pending
Latency: 38ms avg
Uptime: 4d 12h

CLI Reference

Complete command reference. All commands use the cast prefix.