talea

One folder structure for every machine you work on.

talea-run.web.app — the site, and the manual.

You have a laptop, a desktop, and a work machine. On each one, the repo you want is either missing or somewhere you have to go and find. talea fixes that: one catalogue of your GitHub repos, one tree, and a command that makes any machine match it.

~/Workspace/
  ProjectAJ14/
    eklavya/
    Morph/
    d-pilot/
  nonstopio/
    flutter_forge/
    json-viewer/

Same paths on every machine. cd $(talea where eklavya) works everywhere.

Install

npm install -g @ajaykumarnpm/talea

The package is scoped; the command it installs is just talea.

Node 20 or newer. No other dependencies — not at runtime, not to build it.

Your first machine

talea doctor                 # git, SSH and GitHub auth all reachable?
talea init ~/Workspace       # discovers your repos, asks what to keep, clones
talea manifest push          # publish the catalogue so the next machine can read it

init builds the catalogue from your GitHub account the first time — your own repos, every org you belong to, and anything shared with you directly. It then asks what this machine should keep and fills the tree.

Every command works from anywhere after that. Outside the workspace it uses the one init made; with more than one on the machine, it asks which.

Every machine after that

talea manifest pull <gist-id>   # the id `manifest push` printed
talea init ~/Workspace

You are handed the full list with your defaults already ticked. Tick the extras this machine needs, untick what it does not, press enter.

Every day

talea sync                   # clone the new, fast-forward the rest
talea status                 # branch, clean/dirty, ahead/behind, in one table
talea add some-repo          # keep one more on this machine, and clone it now
talea select                 # reopen the checklist and change the whole list
talea pick some-repo          # keep that one — an unknown name opens the checklist
cd $(talea where eklavya)

Let your coding agent do it

talea skill install

Installs a skill into Claude Code at user scope, so every project you open has it. After that "where is eklavya?" and "my repos are scattered, tidy them up" reach the right command — with the guardrails attached: an adopt is always shown as a dry run first, --loose is never taken on your behalf, and a removal is reported as taken off the list rather than as a delete.

talea skill says whether it is installed, talea skill uninstall takes it back out, and it refuses to overwrite a skill called talea that talea did not write.

The repos you already have

This is the part that matters on a machine you have been using for years.

talea never clones a repo you already have. Before cloning anything it scans the workspace — and any folder you name with --from — and matches every checkout it finds by its git remote, not by folder name. A repo cloned into ~/tmp/clone2/whatever is recognised as the repo it holds and moved into place.

A move keeps everything: branches, stashes, the reflog, your uncommitted changes. A re-clone throws all of it away, which is why this tool does not do one.

Worktrees come too. The sibling <repo>-worktrees/ folder moves alongside the repo, and every worktree is re-linked afterwards — the ones that moved and the ones that did not. A worktree is never mistaken for a second copy of the repo, even though git reports the same origin for both.

talea adopt                      # show what would move, change nothing
talea adopt --from ~/Desktop     # look there too; the folder is remembered
talea adopt --apply              # do it

Matching is on the remote URL. When only the name matches — a fork, a mirror, or a directory that merely shares a name — it is listed and left alone; --loose or -r <repo> includes it once you have looked. That guard is not theoretical: an FVM Flutter SDK cache reports origin as flutter/flutter, which name-matches a personal flutter fork, and moving it would break every Flutter project on the machine.

If the same repo turns up twice, the copy at the catalogue path wins and the other moves into .talea-duplicates/ with everything in it. Nothing is ever deleted. Clearing that folder is your call.

After a move, the absolute paths that pointed at the old location are repaired — Claude Code session history and project settings, .idea, .vscode — because a repo that moves and loses its history has not really been helped.

When another tool owns a checkout

Mark it in the catalogue and talea leaves it completely alone:

{ "name": "some-repo", "owner": "someone", "ignore": true }

Without this, two tools that both organise repositories will each drag the same checkout back to where it thinks it belongs, on every run. Use it for repos inside another workspace manager's tree, vendored checkouts, and SDK caches.

What travels, and what does not

| | Where it lives | Shared | |---|---|---| | The catalogue — every repo, its owner, its folder, its default branch | ~/.talea/talea.repos.json | yes, through a private gist | | What this machine keeps | <workspace>/.talea.json | never |

That split is the whole design. Pulling the catalogue onto a new laptop gives you the full list to choose from — not the last machine's choices. Your work laptop can keep three repos while the desktop keeps forty, and neither fights the other.

The gist is private, but it still holds the names of your private repositories. Treat the id like a bookmark you would not paste into a public channel.

Commands

| | | |---|---| | talea init [dir] | create the workspace on this machine and fill it | | talea discover | build or refresh the catalogue from GitHub | | talea sync | clone what is missing, fast-forward what is there | | talea clone | clone only — never fetches or merges | | talea adopt | move checkouts you already have into place | | talea status | branch, clean/dirty, ahead/behind | | talea select | reopen the checklist — talea pick <repo> for one | | talea add / talea rm | change that one repo at a time | | talea where <repo> | print a repo's path, for cd $( ) | | talea list | the catalogue | | talea tree | the folder tree on disk | | talea exec -- <cmd> | run one command in every repo | | talea manifest push/pull | move the catalogue between machines | | talea skill | install the skill that lets your coding agent drive talea | | talea doctor | check this machine can do the work | | talea upgrade | update the CLI itself (also talea update) |

Every one of them takes -g <group> and -r <repo> to narrow the run, and --help for its own examples. For sync, clone, status, list and tree a bare name means the same as -r, so talea sync eklavya syncs that one repo. A command that takes no names refuses a stray word instead of ignoring it.

What it will not do

• It will not push. Read and checkout only.
• It will not throw away uncommitted work. A dirty repo is fetched and left alone, with a line saying so.
• It will not merge a divergence. Fast-forwards only; anything else is reported for you to deal with.
• It will not move you off your branch. If you are on a feature branch, that is where the work is. It fast-forwards the branch you are on, or leaves it.
• It will not delete anything. Not a duplicate, not a checkout you removed from the list, not a folder in the way. It moves things and tells you where.

Auth

Cloning uses SSH (--protocol https if you prefer). Reading the catalogue uses the GitHub API, via the gh CLI if it is installed, else GITHUB_TOKEN, else public repos only — which is a working state, not an error.

If gh is installed, talea uses it for API calls. That is deliberate beyond the token: gh trusts your system's certificate store, so talea keeps working on a machine behind a corporate proxy or VPN where Node's own HTTPS would fail.

Contributing

git clone [email protected]:ProjectAJ14/talea.git
cd talea
npm test          # no install step — there are no dependencies
node bin/talea.js --help

Tests run on macOS, Linux and Windows across Node 20, 22 and 24 on every push.

The website lives in web/ and is its own thing — Astro, deployed to Firebase Hosting on a push to main that touches it. web/CLAUDE.md is how to work on it.

cd web && npm install && npm run dev

Licence

MIT.