Skip to content

README.md

Latest commit

 

History

History
354 lines (261 loc) · 7.77 KB

README.md

File metadata and controls

354 lines (261 loc) · 7.77 KB

Workie - Agentic Coding Assistant CLI

Go Version License: MIT Go Report Card GitHub release

A comprehensive developer assistant that streamlines your coding workflow with advanced Git worktree management, AI-powered features, and Claude Code integration.

Table of Contents

Quick Start

# Install
go install github.com/agoodway/workie@latest

# Initialize configuration
workie init

# Create a new worktree branch
workie begin feature/new-ui

# List worktrees
workie --list

Features

Core Features

  • 🌳 Smart Git Worktree Management - Create and manage git worktrees effortlessly
  • 🤖 AI-Powered Assistant - Generate branch names and commit messages from issue details
  • 📋 Issue Provider Integration - Connect with GitHub, Jira, and Linear
  • 🔔 System Notifications - Get alerts for important events
  • 📁 Smart File Copying - Automatically copy essential files to new worktrees

AI Capabilities

  • Generate descriptive branch names from issue details
  • Create meaningful commit messages
  • Execute git commands with context awareness
  • AI-powered security decisions for tool usage

Installation

Using Go Install (Recommended)

go install github.com/agoodway/workie@latest

Building from Source

# Clone the repository
git clone https://github.com/agoodway/workie.git
cd workie

# Build the binary
go build -o workie .

# Optional: Install to PATH
go install .

Requirements

  • Go 1.21 or higher
  • Git installed and configured
  • Optional: Ollama for AI features

Basic Usage

Worktree Management

# Initialize configuration in your project
workie init

# Create a new worktree with a branch
workie begin feature/new-ui
workie begin bugfix/issue-123

# Create and change to new worktree
workie begin -q feature/new-feature | cd

# List all worktrees
workie --list
workie -l

# Remove a worktree
workie finish feature/completed-work
workie finish feature/old-branch --prune-branch

# Create AI-powered branch names from issues
workie begin --issue 123 --ai
workie begin --issue github:456 --ai

Conflict Monitoring

# Start the watch server to monitor for rebase conflicts
workie watch

# Check every 10 minutes instead of default 5
workie watch --interval 10m

# Use a custom port
workie watch --port 8081

# Run in quiet mode
workie watch --quiet

# Access the watch server API
curl http://localhost:8080/status
curl http://localhost:8080/conflicts
curl -X POST http://localhost:8080/check

Configuration

Workie uses YAML configuration files to customize behavior. Place .workie.yaml in your repository root.

Basic Configuration

# Files to copy to new worktrees
files_to_copy:
  - .env.example
  - scripts/
  - config/development.yaml

# Default issue provider
default_provider: github

Initializing Configuration

The easiest way to get started:

# Create .workie.yaml with examples
workie init

# Create with custom filename
workie init --output my-config.yaml

# Overwrite existing file
workie init --force

AI Features

Setup

  1. Install Ollama
  2. Pull a model: ollama pull zephyr
  3. Configure in .workie.yaml:
ai:
  enabled: true
  model:
    provider: "ollama"
    name: "zephyr"
    temperature: 0.7
    max_tokens: 2048
  ollama:
    base_url: "http://localhost:11434"
    keep_alive: "5m"

Smart Branch Names

# Standard: fix/123-update-user-authentication-to-support-oauth2
workie begin --issue 123

# AI-powered: fix/123-oauth2-auth
workie begin --issue 123 --ai

Issue Provider Integration

GitHub

providers:
  github:
    enabled: true
    settings:
      token_env: "GITHUB_TOKEN"
      owner: "your-org"
      repo: "your-repo"
    branch_prefix:
      bug: "fix/"
      feature: "feat/"
      default: "issue/"

Jira

providers:
  jira:
    enabled: true
    settings:
      base_url: "https://your-company.atlassian.net"
      email_env: "JIRA_EMAIL"
      api_token_env: "JIRA_TOKEN"
      project: "PROJ"
    branch_prefix:
      bug: "bugfix/"
      story: "feature/"
      default: "jira/"

Using Issue Providers

# List issues
workie issues
workie issues --provider github

# View issue details
workie issues github:123
workie issues jira:PROJ-456

# Create worktree from issue
workie issues github:123 --create
workie issues jira:PROJ-456 -c

# Filter issues
workie issues --assignee me --status open
workie issues --labels bug,urgent

Advanced Usage

File Copying

Workie automatically copies specified files to new worktrees:

files_to_copy:
  - .env.example          # Environment template
  - scripts/              # Utility scripts (copied recursively)
  - config/dev.yaml       # Development config
  - docker-compose.yml    # Docker setup

Directory Structure Example:

your-project/                    # Main repository
├── .workie.yaml
├── .env.example
└── scripts/

your-project-worktrees/          # Created automatically
└── feature-new-ui/
    ├── .env.example            # ✓ Copied
    └── scripts/                # ✓ Copied recursively

Troubleshooting

Common Issues

Configuration not found:

# Ensure .workie.yaml exists
ls -la .workie.yaml

# Initialize if missing
workie init

AI features not working:

# Check Ollama is running
ollama list

# Pull required model
ollama pull zephyr

Getting Help

# Show help
workie --help

# Show version and build info
workie --version

# Report issues
# https://github.com/agoodway/workie/issues

How It Works

  1. Repository Detection: Uses git rev-parse --show-toplevel
  2. Configuration Loading: Reads .workie.yaml from repo root
  3. Worktree Creation: Creates <repo>-worktrees/ directory
  4. Branch Management: Creates new branches in separate worktrees
  5. File Copying: Copies configured files to new worktrees

Vision

Workie is evolving into a comprehensive agentic coding assistant that:

  • Learns your patterns - Adapts to your coding style
  • Automates repetitive tasks - From branch creation to testing
  • Provides intelligent suggestions - Context-aware recommendations
  • Integrates seamlessly - Works with your existing tools
  • Evolves with AI - Leverages latest AI technologies

Future roadmap includes:

  • Automated testing generation
  • Intelligent refactoring suggestions
  • Context-aware development assistance
  • Advanced workflow automation

Contributing

We welcome contributions! Please read our Contributing Guide for details.

Quick Start for Contributors

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes and add tests
  4. Commit your changes (git commit -m 'feat: add amazing feature')
  5. Push to the branch (git push origin feature/amazing-feature)
  6. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.