# krishnan-chandra/kstack architecture

> Architecture diagram of the GitHub repository krishnan-chandra/kstack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krishnan-chandra/kstack
- Repository: https://github.com/krishnan-chandra/kstack

## Overview

kstack is a collection of personal Pi extensions. Its user-facing workflows include PR-stack publication and landing, bounded PR maintenance, session/history tools, model routing, and isolated parallel agents. The graph focuses on those runtime extensions and their shared support; README statements establish product behavior, while sampled excerpts and the source index support selected internal links. Unsampled implementation details and connections are omitted rather than inferred.

Main entry points: [`extensions/github-stacked-prs/index.ts`](https://github.com/krishnan-chandra/kstack/blob/main/extensions/github-stacked-prs/index.ts) (GitHub stacks), [`extensions/jj-stacked-prs/index.ts`](https://github.com/krishnan-chandra/kstack/blob/main/extensions/jj-stacked-prs/index.ts) (Jujutsu stacks), [`extensions/land/api.ts`](https://github.com/krishnan-chandra/kstack/blob/main/extensions/land/api.ts) (Landing requests), [`extensions/pr-autopilot/index.ts`](https://github.com/krishnan-chandra/kstack/blob/main/extensions/pr-autopilot/index.ts) (PR autopilot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_stacked_prs["Stacked PRs"]
  node_gh_stack["GitHub stacks<br/>[index.ts]"]
  node_graphite_stack["Graphite stacks<br/>[index.ts]"]
  node_jj_stack["Jujutsu stacks<br/>[index.ts]"]
  node_stack_outcomes["Stack outcomes<br/>[outcome.ts]"]
end

subgraph group_pr_workflows["PR Workflows"]
  node_land["PR landing<br/>[index.ts]"]
  node_land_api["Landing requests<br/>[api.ts]"]
  node_autopilot["PR autopilot<br/>[index.ts]"]
  node_autopilot_api["Autopilot API<br/>[api.ts]"]
end

subgraph group_session_tools["Session Tools"]
  node_session_archive["Session archive<br/>[index.ts]"]
  node_archive_store[("Archive index<br/>[archive-store.ts]")]
  node_handoff["Session handoff<br/>[index.ts]"]
  node_history_search["History search<br/>[history-search.ts]"]
end

subgraph group_agent_routing["Agents and Routing"]
  node_openrouter["Model routing<br/>[index.ts]"]
  node_routing_policy["Routing policy<br/>[routing-policy.ts]"]
  node_parallel_agents["Parallel agents<br/>[index.ts]"]
  node_agent_orchestrator["Agent orchestration<br/>[orchestrator.ts]"]
  node_steering["Editor steering<br/>[index.ts]"]
end

subgraph group_shared_runtime["Shared Runtime"]
  node_git_exec["Git command runner<br/>[git-exec.ts]"]
  node_github_api["GitHub gateway<br/>[github.ts]"]
  node_repo_identity["Repository identity"]
  node_fallthrough["Command guard"]
  node_validation["Boundary validation<br/>[validation.ts]"]
end

node_user(("Pi user"))
node_pi(("Pi host"))
node_github{{"GitHub"}}

node_user -->|"uses extensions"| node_pi
node_pi -->|"invokes commands"| node_gh_stack
node_pi -->|"invokes commands"| node_graphite_stack
node_pi -->|"invokes tools"| node_jj_stack
node_pi -->|"invokes landing"| node_land
node_pi -->|"runs workflow"| node_autopilot
node_pi -->|"opens sessions"| node_session_archive
node_pi -->|"starts handoff"| node_handoff
node_pi -->|"routes models"| node_openrouter
node_pi -->|"runs agents"| node_parallel_agents
node_pi -->|"handles editor input"| node_steering
node_gh_stack -->|"publishes PR stacks"| node_github
node_graphite_stack -->|"publishes PR stacks"| node_github
node_jj_stack -->|"publishes native stacks"| node_github
node_gh_stack -->|"requests landing"| node_land_api
node_jj_stack -->|"requests landing"| node_land_api
node_jj_stack -->|"requests readiness"| node_autopilot_api
node_gh_stack -->|"records outcomes"| node_stack_outcomes
node_jj_stack -->|"renders outcomes"| node_stack_outcomes
node_land -->|"routes requests"| node_land_api
node_autopilot -->|"exposes requests"| node_autopilot_api
node_session_archive -->|"indexes sessions"| node_archive_store
node_handoff -->|"provides search"| node_history_search
node_history_search -->|"searches archive"| node_archive_store
node_openrouter -->|"applies policy"| node_routing_policy
node_parallel_agents -->|"delegates runs"| node_agent_orchestrator
node_repo_identity -->|"runs commands"| node_git_exec
node_repo_identity -->|"resolves repository"| node_github_api
node_github_api -->|"executes requests"| node_git_exec
node_autopilot -->|"guards commands"| node_fallthrough
node_gh_stack -->|"guards commands"| node_fallthrough
node_land_api -->|"validates payloads"| node_validation
node_github_api -->|"checks responses"| node_validation

click node_gh_stack "https://github.com/krishnan-chandra/kstack/blob/main/extensions/github-stacked-prs/index.ts"
click node_graphite_stack "https://github.com/krishnan-chandra/kstack/blob/main/extensions/graphite-stacked-prs/index.ts"
click node_jj_stack "https://github.com/krishnan-chandra/kstack/blob/main/extensions/jj-stacked-prs/index.ts"
click node_stack_outcomes "https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/stack/outcome.ts"
click node_land "https://github.com/krishnan-chandra/kstack/blob/main/extensions/land/index.ts"
click node_land_api "https://github.com/krishnan-chandra/kstack/blob/main/extensions/land/api.ts"
click node_autopilot "https://github.com/krishnan-chandra/kstack/blob/main/extensions/pr-autopilot/index.ts"
click node_autopilot_api "https://github.com/krishnan-chandra/kstack/blob/main/extensions/pr-autopilot/api.ts"
click node_session_archive "https://github.com/krishnan-chandra/kstack/blob/main/extensions/session-archive/index.ts"
click node_archive_store "https://github.com/krishnan-chandra/kstack/blob/main/extensions/session-archive/archive-store.ts"
click node_handoff "https://github.com/krishnan-chandra/kstack/blob/main/extensions/handoff/index.ts"
click node_history_search "https://github.com/krishnan-chandra/kstack/blob/main/extensions/handoff/history-search.ts"
click node_openrouter "https://github.com/krishnan-chandra/kstack/blob/main/extensions/openrouter-routing/index.ts"
click node_routing_policy "https://github.com/krishnan-chandra/kstack/blob/main/extensions/openrouter-routing/routing-policy.ts"
click node_parallel_agents "https://github.com/krishnan-chandra/kstack/blob/main/extensions/parallel-agents/index.ts"
click node_agent_orchestrator "https://github.com/krishnan-chandra/kstack/blob/main/extensions/parallel-agents/orchestrator.ts"
click node_steering "https://github.com/krishnan-chandra/kstack/blob/main/extensions/steering-swap/index.ts"
click node_git_exec "https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/git-exec.ts"
click node_github_api "https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/github.ts"
click node_repo_identity "https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/github-repository.ts"
click node_fallthrough "https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/command-fallthrough.ts"
click node_validation "https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/validation.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gh_stack,node_graphite_stack,node_jj_stack,node_stack_outcomes,node_user toneBlue
class node_land,node_land_api,node_autopilot,node_autopilot_api toneAmber
class node_session_archive,node_archive_store,node_handoff,node_history_search toneMint
class node_openrouter,node_routing_policy,node_parallel_agents,node_agent_orchestrator,node_steering toneRose
class node_git_exec,node_github_api,node_repo_identity,node_fallthrough,node_validation,node_pi,node_github toneIndigo
```

## Components

### Stacked PRs

- [GitHub stacks](https://github.com/krishnan-chandra/kstack/blob/main/extensions/github-stacked-prs/index.ts): `extensions/github-stacked-prs/index.ts`
- [Graphite stacks](https://github.com/krishnan-chandra/kstack/blob/main/extensions/graphite-stacked-prs/index.ts): `extensions/graphite-stacked-prs/index.ts`
- [Jujutsu stacks](https://github.com/krishnan-chandra/kstack/blob/main/extensions/jj-stacked-prs/index.ts): `extensions/jj-stacked-prs/index.ts`
- [Stack outcomes](https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/stack/outcome.ts): `extensions/shared/stack/outcome.ts`

### PR Workflows

- [PR landing](https://github.com/krishnan-chandra/kstack/blob/main/extensions/land/index.ts): `extensions/land/index.ts`
- [Landing requests](https://github.com/krishnan-chandra/kstack/blob/main/extensions/land/api.ts): `extensions/land/api.ts`
- [PR autopilot](https://github.com/krishnan-chandra/kstack/blob/main/extensions/pr-autopilot/index.ts): `extensions/pr-autopilot/index.ts`
- [Autopilot API](https://github.com/krishnan-chandra/kstack/blob/main/extensions/pr-autopilot/api.ts): `extensions/pr-autopilot/api.ts`

### Session Tools

- [Session archive](https://github.com/krishnan-chandra/kstack/blob/main/extensions/session-archive/index.ts): `extensions/session-archive/index.ts`
- [Archive index](https://github.com/krishnan-chandra/kstack/blob/main/extensions/session-archive/archive-store.ts): `extensions/session-archive/archive-store.ts`
- [Session handoff](https://github.com/krishnan-chandra/kstack/blob/main/extensions/handoff/index.ts): `extensions/handoff/index.ts`
- [History search](https://github.com/krishnan-chandra/kstack/blob/main/extensions/handoff/history-search.ts): `extensions/handoff/history-search.ts`

### Agents and Routing

- [Model routing](https://github.com/krishnan-chandra/kstack/blob/main/extensions/openrouter-routing/index.ts): `extensions/openrouter-routing/index.ts`
- [Routing policy](https://github.com/krishnan-chandra/kstack/blob/main/extensions/openrouter-routing/routing-policy.ts): `extensions/openrouter-routing/routing-policy.ts`
- [Parallel agents](https://github.com/krishnan-chandra/kstack/blob/main/extensions/parallel-agents/index.ts): `extensions/parallel-agents/index.ts`
- [Agent orchestration](https://github.com/krishnan-chandra/kstack/blob/main/extensions/parallel-agents/orchestrator.ts): `extensions/parallel-agents/orchestrator.ts`
- [Editor steering](https://github.com/krishnan-chandra/kstack/blob/main/extensions/steering-swap/index.ts): `extensions/steering-swap/index.ts`

### Shared Runtime

- [Git command runner](https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/git-exec.ts): `extensions/shared/git-exec.ts`
- [GitHub gateway](https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/github.ts): `extensions/shared/github.ts`
- [Repository identity](https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/github-repository.ts): `extensions/shared/github-repository.ts`
- [Command guard](https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/command-fallthrough.ts): `extensions/shared/command-fallthrough.ts`
- [Boundary validation](https://github.com/krishnan-chandra/kstack/blob/main/extensions/shared/validation.ts): `extensions/shared/validation.ts`

### Other components

- **Pi user**
- **Pi host**
- **GitHub**

## Connections

- Pi user → Pi host: uses extensions (evidence: `README.md`)
- Pi host → GitHub stacks: invokes commands (evidence: `README.md`)
- Pi host → Graphite stacks: invokes commands (evidence: `README.md`)
- Pi host → Jujutsu stacks: invokes tools (evidence: `README.md`)
- Pi host → PR landing: invokes landing (evidence: `README.md`)
- Pi host → PR autopilot: runs workflow (evidence: `README.md`)
- Pi host → Session archive: opens sessions (evidence: `README.md`)
- Pi host → Session handoff: starts handoff (evidence: `README.md`)
- Pi host → Model routing: routes models (evidence: `README.md`)
- Pi host → Parallel agents: runs agents (evidence: `README.md`)
- Pi host → Editor steering: handles editor input (evidence: `README.md`)
- GitHub stacks → GitHub: publishes PR stacks (evidence: `README.md`)
- Graphite stacks → GitHub: publishes PR stacks (evidence: `README.md`)
- Jujutsu stacks → GitHub: publishes native stacks (evidence: `README.md`)
- GitHub stacks → Landing requests: requests landing (evidence: `extensions/github-stacked-prs/index.ts`)
- Jujutsu stacks → Landing requests: requests landing (evidence: `extensions/jj-stacked-prs/index.ts`)
- Jujutsu stacks → Autopilot API: requests readiness (evidence: `extensions/jj-stacked-prs/index.ts`)
- GitHub stacks → Stack outcomes: records outcomes (evidence: `extensions/github-stacked-prs/index.ts`)
- Jujutsu stacks → Stack outcomes: renders outcomes
- PR landing → Landing requests: routes requests (evidence: `extensions/land/index.ts`)
- PR autopilot → Autopilot API: exposes requests (evidence: `extensions/pr-autopilot/index.ts`)
- Session archive → Archive index: indexes sessions (evidence: `extensions/session-archive/index.ts`)
- Session handoff → History search: provides search (evidence: `extensions/handoff/index.ts`)
- History search → Archive index: searches archive (evidence: `extensions/handoff/history-search.ts`)
- Model routing → Routing policy: applies policy (evidence: `extensions/openrouter-routing/index.ts`)
- Parallel agents → Agent orchestration: delegates runs (evidence: `extensions/parallel-agents/index.ts`)
- Repository identity → Git command runner: runs commands (evidence: `extensions/shared/github-repository.ts`)
- Repository identity → GitHub gateway: resolves repository (evidence: `extensions/shared/github-repository.ts`)
- GitHub gateway → Git command runner: executes requests (evidence: `extensions/shared/github.ts`)
- PR autopilot → Command guard: guards commands (evidence: `extensions/pr-autopilot/index.ts`)
- GitHub stacks → Command guard: guards commands (evidence: `extensions/github-stacked-prs/index.ts`)
- Landing requests → Boundary validation: validates payloads (evidence: `extensions/land/api.ts`)
- GitHub gateway → Boundary validation: checks responses (evidence: `extensions/shared/github.ts`)
