๐๐ผโโ๏ธ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.
Rust adeai-agentsclaudeclaude-codecodexcursorgeminigrokopencodespec-driven-developmentvibe-codingvim
add README, install script and release workflow
fynnflueggeb0dfd2c56b0e
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlnew file mode 100644index 0000000..78b41e2--- /dev/null+++ b/.github/workflows/release.yml@@ -0,0 +1,91 @@+name: Release++on:+ push:+ tags:+ - 'v*'++env:+ CARGO_TERM_COLOR: always++jobs:+ build:+ name: Build ${{ matrix.target }}+ runs-on: ${{ matrix.os }}+ strategy:+ matrix:+ include:+ # macOS+ - target: aarch64-apple-darwin+ os: macos-latest+ archive: agtx-${{ github.ref_name }}-aarch64-darwin.tar.gz+ - target: x86_64-apple-darwin+ os: macos-latest+ archive: agtx-${{ github.ref_name }}-x86_64-darwin.tar.gz+ # Linux+ - target: x86_64-unknown-linux-gnu+ os: ubuntu-latest+ archive: agtx-${{ github.ref_name }}-x86_64-linux.tar.gz+ - target: aarch64-unknown-linux-gnu+ os: ubuntu-latest+ archive: agtx-${{ github.ref_name }}-aarch64-linux.tar.gz++ steps:+ - uses: actions/checkout@v4++ - name: Install Rust+ uses: dtolnay/rust-toolchain@stable+ with:+ targets: ${{ matrix.target }}++ - name: Install cross-compilation tools (Linux aarch64)+ if: matrix.target == 'aarch64-unknown-linux-gnu'+ run: |+ sudo apt-get update+ sudo apt-get install -y gcc-aarch64-linux-gnu++ - name: Build+ run: |+ if [[ "${{ matrix.target }}" == "aarch64-unknown-linux-gnu" ]]; then+ export CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc+ fi+ cargo build --release --target ${{ matrix.target }}++ - name: Package+ run: |+ cd target/${{ matrix.target }}/release+ tar -czvf ../../../${{ matrix.archive }} agtx+ cd ../../..++ - name: Upload artifact+ uses: actions/upload-artifact@v4+ with:+ name: ${{ matrix.archive }}+ path: ${{ matrix.archive }}++ release:+ name: Create Release+ needs: build+ runs-on: ubuntu-latest+ permissions:+ contents: write++ steps:+ - uses: actions/checkout@v4++ - name: Download all artifacts+ uses: actions/download-artifact@v4+ with:+ path: artifacts+ merge-multiple: true++ - name: List artifacts+ run: ls -la artifacts/++ - name: Create Release+ uses: softprops/action-gh-release@v2+ with:+ files: artifacts/*.tar.gz+ generate_release_notes: true+ draft: false+ prerelease: ${{ contains(github.ref_name, '-') }}diff --git a/CLAUDE.md b/CLAUDE.mdindex 851e2dc..93fb599 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -11,7 +11,7 @@ cargo build --release# Run in a git project directory./target/release/agtx-# Or run in dashboard mode+# Or run in dashboard mode (no git project required)./target/release/agtx -g```@@ -28,16 +28,16 @@ src/โโโ db/โ โโโ mod.rs # Re-exportsโ โโโ schema.rs # Database struct, SQLite operations-โ โโโ models.rs # Task, Project, TaskStatus, AgentStatus enums+โ โโโ models.rs # Task, Project, TaskStatus enumsโโโ tmux/-โ โโโ mod.rs # Tmux server "agents", session management+โ โโโ mod.rs # Tmux server "agtx", session managementโโโ git/โ โโโ mod.rs # is_git_repo helperโ โโโ worktree.rs # Git worktree create/remove/listโโโ agent/โ โโโ mod.rs # Agent definitions, detection, spawn argsโโโ config/- โโโ mod.rs # GlobalConfig, ProjectConfig, MergedConfig+ โโโ mod.rs # GlobalConfig, ProjectConfig, ThemeConfig, MergedConfig```## Key Concepts@@ -45,15 +45,22 @@ src/### Task Workflow```Backlog โ Planning โ Running โ Review โ Done- โ โ โ- worktree Claude PR opens- created starts+ โ โ โ โ+ worktree Claude PR opens cleanup+ + Claude working (can (keep+ planning resume) branch)```-- **Planning**: Creates git worktree at `.agtx/worktrees/{slug}`, starts Claude Code session-- **Running**: Claude is implementing (tmux session active)-- **Review**: PR is opened, awaiting review. Can move back to Running for changes-- **Done**: PR merged, cleanup worktree/branch/tmux session+- **Backlog**: Task ideas, not started+- **Planning**: Creates git worktree at `.agtx/worktrees/{slug}`, starts Claude Code in planning mode+- **Running**: Claude is implementing (sends "proceed with implementation")+- **Review**: PR is opened. Can move back to Running to address feedback (resumes Claude session)+- **Done**: PR merged/closed, cleanup worktree + tmux (branch kept for potential reopen)++### Claude Session Resume+- When Claude starts, session is renamed with `/rename {task_id}`+- When resuming from Review โ Running, uses `claude --resume {task_id}`+- This preserves full conversation context across task lifecycle### Database StorageAll databases stored centrally (not in project directories):@@ -65,31 +72,63 @@ Structure:- `projects/{hash}.db` - Per-project task database (hash of project path)### Tmux Architecture-- All agent sessions run in tmux server named `agents` (`tmux -L agents`)-- Session naming: `task-{id}--{project}--{slug}`+- All agent sessions run in tmux server named `agtx` (`tmux -L agtx`)+- Window naming: `{project}:task-{title_slug}`- Separate from user's regular tmux sessions+- View sessions: `tmux -L agtx list-windows`++### Theme Configuration+Colors configurable via `~/.config/agtx/config.toml`:+```toml+[theme]+color_selected = "#FFFF99" # Selected elements (light yellow)+color_normal = "#00FFFF" # Normal borders (cyan)+color_dimmed = "#666666" # Inactive elements (gray)+color_text = "#FFFFFF" # Text (white)+color_accent = "#00FFFF" # Accents (cyan)+color_description = "#E8909C" # Task descriptions (rose)+```-## Keyboard Shortcuts (Board Mode)+## Keyboard Shortcuts+### Board Mode| Key | Action ||-----|--------|-| `h/l` | Move between columns |-| `j/k` | Move between tasks |+| `h/l` or arrows | Move between columns |+| `j/k` or arrows | Move between tasks || `o` | Create new task |-| `Enter` | Open task shell popup |-| `i` | Edit task |-| `d` | Delete task |-| `m` | Move task right (advance workflow) |-| `/` | Search tasks |+| `Enter` | Open task popup (tmux view) |+| `i` | Edit task (backlog only) |+| `x` | Delete task |+| `d` | Show git diff for task |+| `m` | Move task forward (advance workflow) |+| `r` | Resume task (Review โ Running) |+| `/` | Search tasks (jumps to and opens task) || `e` | Toggle project sidebar || `q` | Quit |+### Task Popup (tmux view)+| Key | Action |+|-----|--------|+| `Ctrl+j/k` | Scroll up/down |+| `Ctrl+g` | Jump to bottom |+| `Ctrl+q` | Close popup |+| Other keys | Forwarded to tmux/Claude |++### PR Creation Popup+| Key | Action |+|-----|--------|+| `Tab` | Switch between title/description |+| `Ctrl+s` | Create PR and move to Review |+| `Esc` | Cancel |+## Code Patterns### Ratatui TUI- Uses `crossterm` backend- State separated from terminal for borrow checker: `App { terminal, state: AppState }`- Drawing functions are static: `fn draw_*(state: &AppState, frame: &mut Frame, area: Rect)`+- Theme colors accessed via `state.config.theme.color_*`### Error Handling- Use `anyhow::Result` for all fallible functions@@ -101,6 +140,17 @@ Structure:- Migrations via `ALTER TABLE ... ADD COLUMN` (ignores errors if column exists)- DateTime stored as RFC3339 strings+### Background Operations+- PR description generation runs in background thread+- PR creation runs in background thread+- Uses `mpsc` channels to communicate results back to main thread+- Loading spinners shown during async operations++### Claude Integration+- Uses `--dangerously-skip-permissions` flag+- Polls tmux pane for "Yes, I accept" prompt before sending acceptance+- Sends `/rename {task_id}` after Claude starts for session resume capability+## Building```bash@@ -112,6 +162,8 @@ Dependencies require:- SQLite (bundled via rusqlite)- tmux (runtime dependency)- git (runtime dependency)+- gh CLI (for PR operations)+- claude CLI (Claude Code)## Testing@@ -127,6 +179,11 @@ cargo test3. Update `create_task`, `update_task`, `task_from_row` in schema.rs4. Update UI rendering in `src/tui/app.rs`+### Adding a new theme color+1. Add field to `ThemeConfig` in `src/config/mod.rs`+2. Add default function and update `Default` impl+3. Use `hex_to_color(&state.config.theme.color_*)` in app.rs+### Adding a new agent1. Add to `known_agents()` in `src/agent/mod.rs`2. Add spawn args handling in `build_spawn_args()`@@ -136,3 +193,16 @@ cargo test1. Find the appropriate `handle_*_key` function in `src/tui/app.rs`2. Add match arm for the new key3. Update help/footer text if visible to user++### Adding a new popup+1. Add state struct (e.g., `MyPopup`) in app.rs+2. Add `Option<MyPopup>` field to `AppState`+3. Add rendering in `draw_board()` function+4. Add key handler function `handle_my_popup_key()`+5. Add check in `handle_key()` to route to handler++## Future Enhancements+- Auto-detect Claude idle status (show spinner when working)+- Reopen Done tasks (recreate worktree from preserved branch)+- Support for additional agents (Aider, Codex)+- Notification when Claude finishes workdiff --git a/README.md b/README.mdindex 320382e..5369d2e 100644--- a/README.md+++ b/README.md@@ -1 +1,159 @@-# agtx\ No newline at end of file+# agtx++A terminal-native kanban board for managing coding agent sessions with isolated git worktrees.++++## Features++- **Kanban workflow**: Backlog โ Planning โ Running โ Review โ Done+- **Git worktree isolation**: Each task gets its own worktree, keeping work separated+- **Claude Code integration**: Automatic session management with resume capability+- **PR workflow**: Generate descriptions with AI, create PRs directly from the TUI+- **Multi-project dashboard**: Manage tasks across all your projects+- **Customizable themes**: Configure colors via config file++## Installation++### Quick Install (recommended)++```bash+curl -fsSL https://raw.githubusercontent.com/USER/agtx/main/install.sh | bash+```++### From Source++```bash+git clone https://github.com/USER/agtx.git+cd agtx+cargo build --release+cp target/release/agtx ~/.local/bin/+```++### Requirements++- **tmux** - Agent sessions run in a dedicated tmux server+- **git** - For worktree management+- **gh** - GitHub CLI for PR operations+- **claude** - Claude Code CLI (optional, for Claude integration)++## Quick Start++```bash+# Run in any git repository+cd your-project+agtx++# Or run in dashboard mode (manage all projects)+agtx -g+```++## Usage++### Keyboard Shortcuts++| Key | Action |+|-----|--------|+| `h/l` or `โ/โ` | Move between columns |+| `j/k` or `โ/โ` | Move between tasks |+| `o` | Create new task |+| `Enter` | Open task (view Claude session) |+| `m` | Move task forward in workflow |+| `r` | Resume task (Review โ Running) |+| `d` | Show git diff |+| `x` | Delete task |+| `/` | Search tasks |+| `e` | Toggle project sidebar |+| `q` | Quit |++### Task Workflow++1. **Create a task** (`o`): Enter title and description+2. **Move to Planning** (`m`): Creates worktree, starts Claude in planning mode+3. **Move to Running** (`m`): Claude implements the plan+4. **Move to Review** (`m`): Opens PR with AI-generated description+5. **Move to Done** (`m`): Cleans up after PR is merged++### Claude Session Features++- Sessions automatically resume when moving Review โ Running+- Full conversation context is preserved across the task lifecycle+- View live Claude output in the task popup++## Configuration++Config file location: `~/.config/agtx/config.toml`++```toml+# Default agent for new tasks+default_agent = "claude"++[worktree]+enabled = true+auto_cleanup = true+base_branch = "main"++[theme]+color_selected = "#FFFF99"+color_normal = "#00FFFF"+color_dimmed = "#666666"+color_text = "#FFFFFF"+color_accent = "#00FFFF"+color_description = "#E8909C"+```++## How It Works++### Architecture++```+โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ+โ agtx TUI โ+โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค+โ Backlog โ Planning โ Running โ Review โ Done โ+โ โโโโโโโ โ โโโโโโโ โ โโโโโโโ โ โโโโโโโ โ โ+โ โTask1โ โ โTask2โ โ โTask3โ โ โTask4โ โ โ+โ โโโโโโโ โ โโโโโโโ โ โโโโโโโ โ โโโโโโโ โ โ+โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ+ โ โ+ โผ โผ+ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ+ โ tmux server "agtx" โ+ โ โโโโโโโโโ โโโโโโโโโ โ+ โ โClaude โ โClaude โ โ+ โ โTask2 โ โTask3 โ โ+ โ โโโโโโโโโ โโโโโโโโโ โ+ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ+ โ โ+ โผ โผ+ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ+ โ Git Worktrees โ+ โ .agtx/worktrees/task2/ โ+ โ .agtx/worktrees/task3/ โ+ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโ+```++### Data Storage++- **Database**: `~/Library/Application Support/agtx/` (macOS) or `~/.config/agtx/` (Linux)+- **Worktrees**: `.agtx/worktrees/` in each project+- **Tmux sessions**: Dedicated server `agtx` (view with `tmux -L agtx ls`)++## Development++See [CLAUDE.md](CLAUDE.md) for development documentation.++```bash+# Build+cargo build++# Run tests+cargo test++# Build release+cargo build --release+```++## License++MITdiff --git a/install.sh b/install.shnew file mode 100644index 0000000..431b1ef--- /dev/null+++ b/install.sh@@ -0,0 +1,175 @@+#!/bin/bash+set -e++# agtx installer+# Usage: curl -fsSL https://raw.githubusercontent.com/USER/agtx/main/install.sh | bash++REPO="USER/agtx"+BINARY_NAME="agtx"+INSTALL_DIR="${AGTX_INSTALL_DIR:-$HOME/.local/bin}"++# Colors+RED='\033[0;31m'+GREEN='\033[0;32m'+YELLOW='\033[0;33m'+BLUE='\033[0;34m'+NC='\033[0m' # No Color++info() {+ echo -e "${BLUE}==>${NC} $1"+}++success() {+ echo -e "${GREEN}==>${NC} $1"+}++warn() {+ echo -e "${YELLOW}==>${NC} $1"+}++error() {+ echo -e "${RED}==>${NC} $1"+ exit 1+}++# Detect OS+detect_os() {+ case "$(uname -s)" in+ Linux*) echo "linux" ;;+ Darwin*) echo "darwin" ;;+ *) error "Unsupported OS: $(uname -s)" ;;+ esac+}++# Detect architecture+detect_arch() {+ case "$(uname -m)" in+ x86_64) echo "x86_64" ;;+ amd64) echo "x86_64" ;;+ arm64) echo "aarch64" ;;+ aarch64) echo "aarch64" ;;+ *) error "Unsupported architecture: $(uname -m)" ;;+ esac+}++# Get latest release version+get_latest_version() {+ curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" | \+ grep '"tag_name"' | \+ sed -E 's/.*"([^"]+)".*/\1/'+}++# Main installation+main() {+ echo ""+ echo " โญโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ"+ echo " โ agtx installer โ"+ echo " โ Terminal Kanban โ"+ echo " โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ"+ echo ""++ OS=$(detect_os)+ ARCH=$(detect_arch)++ info "Detected: ${OS}/${ARCH}"++ # Check for required tools+ if ! command -v curl &> /dev/null; then+ error "curl is required but not installed"+ fi++ # Get latest version+ info "Fetching latest version..."+ VERSION=$(get_latest_version)++ if [ -z "$VERSION" ]; then+ error "Could not determine latest version. Check https://github.com/${REPO}/releases"+ fi++ info "Latest version: ${VERSION}"++ # Construct download URL+ ARCHIVE_NAME="${BINARY_NAME}-${VERSION}-${ARCH}-${OS}.tar.gz"+ DOWNLOAD_URL="https://github.com/${REPO}/releases/download/${VERSION}/${ARCHIVE_NAME}"++ # Create temp directory+ TMP_DIR=$(mktemp -d)+ trap "rm -rf ${TMP_DIR}" EXIT++ # Download+ info "Downloading ${ARCHIVE_NAME}..."+ if ! curl -fsSL "${DOWNLOAD_URL}" -o "${TMP_DIR}/${ARCHIVE_NAME}"; then+ error "Download failed. Check if release exists: ${DOWNLOAD_URL}"+ fi++ # Extract+ info "Extracting..."+ tar -xzf "${TMP_DIR}/${ARCHIVE_NAME}" -C "${TMP_DIR}"++ # Create install directory if needed+ if [ ! -d "${INSTALL_DIR}" ]; then+ info "Creating ${INSTALL_DIR}..."+ mkdir -p "${INSTALL_DIR}"+ fi++ # Install binary+ info "Installing to ${INSTALL_DIR}/${BINARY_NAME}..."+ mv "${TMP_DIR}/${BINARY_NAME}" "${INSTALL_DIR}/${BINARY_NAME}"+ chmod +x "${INSTALL_DIR}/${BINARY_NAME}"++ # Check if install dir is in PATH+ if [[ ":$PATH:" != *":${INSTALL_DIR}:"* ]]; then+ warn "${INSTALL_DIR} is not in your PATH"+ echo ""+ echo "Add it to your shell config:"+ echo ""+ echo " # For bash (~/.bashrc)"+ echo " export PATH=\"\$HOME/.local/bin:\$PATH\""+ echo ""+ echo " # For zsh (~/.zshrc)"+ echo " export PATH=\"\$HOME/.local/bin:\$PATH\""+ echo ""+ fi++ echo ""+ success "agtx ${VERSION} installed successfully!"+ echo ""+ echo " Get started:"+ echo " cd your-project"+ echo " agtx"+ echo ""+ echo " Or run in dashboard mode:"+ echo " agtx -g"+ echo ""++ # Check dependencies+ echo " Checking dependencies..."++ if command -v tmux &> /dev/null; then+ echo -e " ${GREEN}โ${NC} tmux"+ else+ echo -e " ${RED}โ${NC} tmux (required)"+ fi++ if command -v git &> /dev/null; then+ echo -e " ${GREEN}โ${NC} git"+ else+ echo -e " ${RED}โ${NC} git (required)"+ fi++ if command -v gh &> /dev/null; then+ echo -e " ${GREEN}โ${NC} gh"+ else+ echo -e " ${YELLOW}โ${NC} gh (optional, for PR operations)"+ fi++ if command -v claude &> /dev/null; then+ echo -e " ${GREEN}โ${NC} claude"+ else+ echo -e " ${YELLOW}โ${NC} claude (optional, for Claude Code integration)"+ fi++ echo ""+}++main "$@"