Astrolabe/User guide
Know what Git will do next.
Astrolabe turns repository state into a workflow you can read. Open a repo, inspect the graph, prepare focused commits, and resolve conflicts with the context that raw markers leave out.
On this page
First five minutesChoose a workspaceEveryday workflowsResolve conflictsWork confidentlyTroubleshootingYour first five minutes.
The shortest useful path through Astrolabe is open, inspect, stage, and commit. Nothing is hidden behind a setup wizard.
Open or clone a repository
From the welcome screen, open a folder that already contains a Git repository, choose a recent repo, or clone from a remote URL.
Read local changes
Graph opens first. Select a changed file to see its diff before deciding what belongs in the next commit.
Stage a focused change
Stage a whole file, a hunk, or selected lines. The staged list is the exact content of your next commit.
Commit and synchronize
Write the reason for the change, commit it, then pull or push when the ahead and behind counts say it is time.
Your system Git configuration, credential helper, SSH keys, signing setup, and hooks keep working. Astrolabe does not ask you to store a GitHub token in the app.
Start from the job, not the menu.
Each top-level workspace answers a different question. Move between them without changing the repository underneath you.
What changed?
Read history, inspect local work, stage, commit, switch branches, stash, pull, and push.
Why do these sides disagree?
Compare both sides with author and commit context, choose a result, and finish the Git operation.
Which agent task needs me?
Run isolated coding tasks, monitor their state, review every changed file, and deliver the result.
Use the top navigation to switch workspaces. Open Settings > Shortcuts for the complete shortcut map on your platform.
Keep the common paths predictable.
Astrolabe keeps the action close to the state it changes, and names the outcome before you confirm it.
Switch branches
Choose a branch from the sidebar. If checkout would overwrite local work, Astrolabe offers to stash the changes and switch safely.
Set work aside
Use Stash when changes are not ready for a commit but you need a clean working tree. Give the stash a message you will recognize later.
Inspect a commit
Select a commit in Graph to see its metadata and files. Select a file to read the exact diff that commit introduced.
Pull and push
Pull when the upstream has commits you do not have. Push when your branch has reviewed commits ready to share.
Recover an operation
The toolbar records supported operations with clear Undo and Redo labels. Read the operation name before moving history.
A conflict should explain where it came from.
Raw conflict markers show two versions. Author Lens adds the author, commit, time, and task context you need to make a decision.
Compare intent, not only syntax
Use the author and commit subject to understand why each side exists.
Take, combine, or edit
Choose yours, theirs, both, or edit the final result directly.
Read the resolved result
Check that the combined code preserves the behavior you intended.
Continue the Git operation
Complete the merge, rebase, or Fleet landing only after every hunk is resolved.
Git swaps the internal meaning of ours and theirs during rebase. Astrolabe keeps the visible labels focused on whose work you are reading.
Know the consequence before the click.
The safest Git client is not the one that removes powerful actions. It is the one that makes their scope and recovery path clear.
Force push
Astrolabe uses force-with-lease and asks for confirmation because the remote branch will be rewritten. Continue only when you know who else uses it.
Discard
Destructive changes go through an explicit confirmation. Read which files and worktree will be affected before continuing.
Long operations
Clone, pull, push, and large history reads show progress so you can distinguish active work from a stalled command.
External changes
Astrolabe watches the open repository. After changing it in an IDE or terminal, give the app a moment to refresh before the next action.
Start with the same command Git would run.
Astrolabe builds on your local Git environment. A quick terminal check usually tells you whether the problem is the repo, credentials, or the app.
A repository will not open
Confirm the folder exists and contains a valid Git repository. Run git status inside it. If Git cannot read the repository, fix that error first and try again.
Pull or push cannot authenticate
Test the same remote with system Git in a terminal. Astrolabe uses the same credential helper or SSH keys, so a working terminal setup is the fastest proof.
The changes you expect are missing
Confirm the correct repository and branch are open. Check whether Git ignores the file, then wait briefly for the repository watcher to refresh.
A Fleet agent does not start
Run the configured agent command in a normal terminal. Fix its installation or authentication first, then check the repository's Fleet launch and setup commands.
Ready to run several agent tasks?
Fleet adds worktree isolation, visible task states, file-by-file review, and deliberate delivery.