Task-centric poly-repo development

Turn your development process on its head

Don’t work on a repo — work on a task across multiple repos as if they were one.

Get Started View on GitHub

Terminal

$ astrolabe start -g community -t add-user-dirs pathway xdg-base-directory

$ ls ~/Projects/community/add-user-dirs/

.envrc pathway/ xdg-base-directory/

Get notified when the alpha drops

One message when it’s ready — no list, no marketing.

Multi-repo development is broken

Modern software is spread across many repositories. The standard workflow — clone each one, open each one, manually coordinate branches — doesn’t scale.

Features span many repos

A single feature often touches 3, 5, or 10 repositories. Coordinating changes across all of them is manual and error-prone.

Branch coordination is manual

You clone each repo, create branches in each, and hope you don't lose track of which repos are part of which task.

Dependencies get stale

While working on repo A, you need the latest changes from repo B. But B is pointed at an old version, and wiring up local overrides is tedious.

Context-switching destroys focus

Different VCS tools, different package managers, different directory structures. Each repo is its own island.

Without Astrolabe

~/src/api-server/ # branch: main

~/work/sdk/ # branch: add-auth

~/projects/cli-tool/ # branch: feature-x

~/repos/shared-types/ # forgot to checkout

Scattered locations. Inconsistent branches. No dependency wiring.

With Astrolabe

~/Projects/work/add-auth/

.envrc # Nix overrides

api-server/ # branch: add-auth

sdk/ # branch: add-auth

cli-tool/ # branch: add-auth

shared-types/ # branch: add-auth

One directory. Same branch everywhere. Dependencies wired automatically.

Built for polyglot development

Astrolabe abstracts over your VCS and build tools so you can focus on the task, not the tooling.

VCS-agnostic

Works with Git, Jujutsu, Mercurial, and Pijul. Auto-detects which VCS each repo uses. CVS, SVN, and DARCS coming soon.

Build-tool-agnostic

Generates local overrides for Cabal, Cargo, NPM, PNPM, and Yarn. Each repo sees its siblings as local dependencies automatically.

Nix-native

Integrates with flakes, direnv, and nix-direnv. A hook flake composes sibling repos' overlays automatically.

Non-destructive

Never deletes your original repos. Suggests cleanup after migration. Only safe branch deletion.

Minimal intrusion

Projects opt in via a single flake input. Everything else is generated outside the source tree or in gitignored files.

Task lifecycle

Start, add, remove, finish, abandon, move, migrate. Full lifecycle management for cross-repo tasks.

How it works

Four steps from scattered repos to a unified task workspace.

Configure your repos

-- ~/.config/astrolabe/config.dhall
{ worktreeBaseDir = Some "/home/you/Projects"
, repos = toMap
    { my-api = { url = "https://github.com/you/my-api" }
    , my-sdk = { url = "https://github.com/you/my-sdk" }
    , my-cli = { url = "https://github.com/you/my-cli" }
    }
}

Start a task

One command creates bare clones, worktrees, .envrc, and build overrides for every repo in your task.

$ astrolabe start -g work -t add-auth my-api my-sdk my-cli

Starting task: work/add-auth
Repos: my-api, my-sdk, my-cli
  Cloning my-api...
  Cloning my-sdk...
  Cloning my-cli...
  Generated .envrc
  Generated cabal.project.local

Work across repos

All repos live in one directory, on the same branch. Siblings are wired as local dependencies automatically.

$ ls ~/Projects/work/add-auth/
.envrc  my-api/  my-sdk/  my-cli/

$ cd my-api && cabal build all   # siblings resolved automatically
$ cd ../my-sdk && nix build      # Nix overrides applied via .envrc

Finish

Astrolabe verifies all branches are merged and cleans up worktrees. Or abandon to discard.

$ astrolabe finish
  All branches merged. Cleaning up worktrees...
  Done.

See it in action

Start a task, add repos, work across them, and finish — all from the command line.

Terminal

How Astrolabe compares

Astrolabe takes a fundamentally different approach: organizing by task, not by repository.

Feature	Astrolabe	Monorepo	Git Submodules	Google repo	meta
Organizes by task		N/A
Multi-VCS support		N/A
Multiple build tools		~	N/A	N/A	N/A
Auto dependency wiring		~
Nix integration
Branch coordination		N/A		~
Non-destructive		N/A		N/A	N/A
Per-task isolation				~
Cleanup tooling		N/A
Setup overhead	One config file	Major restructuring	.gitmodules per consumer	XML manifest	.meta file

Under the hood

Astrolabe uses bare clones as a shared cache. Worktrees are lightweight checkouts that point back to the clone. Generated files wire everything together.

Config

config.dhall

my-api: github.com/...

my-sdk: github.com/...

my-cli: github.com/...

Nicknames + URLs for your repos

Bare Clones

~/.local/state/astrolabe/clones/

my-api/

my-sdk/

my-cli/

Shared cache — one per repo, used across all tasks

Task Worktrees

~/Projects/work/add-auth/

.envrc

my-api/ ← clone

my-sdk/ ← clone

my-cli/ ← clone

Lightweight checkouts — all on the same branch

Generated Files

.envrc

Nix --override-input flags

cabal.project.local

Sibling package paths

hook/flake.nix

Nix overlay for siblings

Result:cabal build, nix build, and your editor all resolve cross-repo references automatically.

Get started

Install Astrolabe, configure your repos, and start your first cross-repo task in minutes.

1Install

# With Nix (recommended)
nix profile install github:sellout/astrolabe

# With Cabal
cabal install astrolabe-cli

# Verify
astrolabe --help

2Configure your repos

-- ~/.config/astrolabe/config.dhall
{ worktreeBaseDir = Some "/home/you/Projects"
, repos = toMap
    { my-api = { url = "https://github.com/you/my-api" }
    , my-sdk = { url = "https://github.com/you/my-sdk" }
    , my-cli = { url = "https://github.com/you/my-cli" }
    }
}

3Start your first task

$ astrolabe start -g work -t add-auth my-api my-sdk my-cli

Result

~/Projects/work/add-auth/

.envrc

my-api/ # on branch "add-auth"

my-sdk/ # on branch "add-auth"

my-cli/ # on branch "add-auth"

4Work and finish

# cd into any repo — siblings are already local dependencies
cd ~/Projects/work/add-auth/my-api
cabal build all    # or: nix build, cargo build, npm run build

# When you're done
astrolabe finish   # verifies merges, cleans up worktrees