alabs

alabs is a local macOS workspace for understanding the engineering environment around your software, and for working on that software in the same place.

alabs is for people who can build working software, often with AI coding tools, but who do not fully understand the files, configuration, Git state and connections that make it work. I built it for myself first. I am one of those people.

alabs does not hide the real project behind a new format. You work on the real files, in the real folders. alabs adds ways to see what is there: facts about each folder, rendered documentation, Git changes, and saved maps whose every box points to real files.

I built alabs to help close that gap for myself. I wanted a workspace that could show me what exists, help explain how the pieces connect, and still let me work in the real repository instead of hiding it behind another system.

What it does

You choose one folder, the alabs root. Each folder inside it is a work folder, which can be a repository or any ordinary folder. All project file access is bounded to that root.

Try it

alabs runs on macOS only and is built from source. There is no signed download. The versions below are what it was tested on, not minimum requirements.

Get the source:

git clone https://github.com/dan-sheehan/alabs.git

Move into it:

cd alabs

Install the exact dependency versions in package-lock.json:

npm ci

Run it in development mode. The first run compiles the Rust side and takes a few minutes:

npm run tauri dev

On first launch

alabs asks you to choose your alabs root. Pick a folder that holds projects, not a project itself. A new empty folder is the safest choice. Clone or move projects into it.

Do not pick a single project. If you do, each of its subfolders becomes a work folder.

alabs does not watch the disk. If something changes outside the app, click Refresh.

To build an unsigned alabs.app, which lands in src-tauri/target/release/bundle/macos/:

npm run tauri build

In Chrome instead

The same interface runs in Google Chrome. A local server owns one root:

npm run browser -- "/absolute/path/to/your/alabs-root"

This builds the browser bundle and the alabs-serve binary, starts the server on 127.0.0.1:43821, and opens Chrome. Control-C stops it. Closing Chrome does not.

Chrome does everything above except move, rename and delete. Those controls tell you so: do it in Finder, then click Refresh. Chrome also keeps unsaved edits as recoverable drafts. Details are in ARCHITECTURE.md.

Optional: a local model

Only Raven and Ask need a model. Both talk to Ollama at 127.0.0.1:11434. alabs never installs or starts Ollama.

Raven uses the model named in its CREATURE.md:

ollama pull qwen3.5:9b

Ask uses whichever installed model you pick in the app.

Checks

Frontend tests:

npm test

Rust tests:

cargo test --manifest-path src-tauri/Cargo.toml

Type check and build:

npm run build

End-to-end tests in Chrome. Google Chrome must be installed. This command builds the browser assets and server first; stop any running alabs browser server so the tests can use port 43821:

npm run test:browser

What it touches

• Inside the root: alabs reads files, and writes only after you act. The Rust side refuses any path that leaves the root.
• App data: ~/Library/Application Support/me.dannysheehan.alabs/ for the desktop app, or ~/Library/Application Support/alabs-browser/ for Chrome. These hold the remembered layout and a small log. The Chrome folder also holds recovery/, which is your unsaved work. Do not delete it.
• The macOS Trash: Delete on the desktop moves files there. Nothing is permanently deleted.
• Terminal.app: only when you click Open in Terminal. Terminal then has its normal permissions.
• Ollama on loopback: only when you start Raven or Ask.

No accounts. No cloud sync. No telemetry. No hosted backend.

Limits

• This is early software, built for my own use first. Expect rough edges.
• macOS only, from source only. The browser version supports Chrome only.
• Chrome cannot move, rename or delete yet. Draft recovery exists only in Chrome.
• Files over 2 MB do not open in the editor and are not searched.
• Each Git call is limited to five seconds and 2 MB of output. A very large repository may report that there is too much to show.
• A work folder whose .git is a file (a worktree or submodule) is shown as linked and is not inspected.
• A map is only as good as its evidence. Raven leaves out what it cannot prove, so a map can be thin.

Learn more

• what-is-alabs.md: what alabs is for, what it is not, and its vocabulary.
• PRINCIPLES.md: the rules that decide design questions.
• ARCHITECTURE.md: how it works, where the boundaries are, and what can fail.
• docs/design.md: the visual and written language.
• creatures/, views/, definitions/: the creature contract, the Visual View format and the glossary.

Contributing and reporting

Use GitHub Issues for bugs. Do not include credentials, keys or private file contents. Report security problems through GitHub's private vulnerability reporting. If a document says alabs does something the source does not do, that is a bug.

Pull requests are judged against what-is-alabs.md and PRINCIPLES.md. Small changes that keep alabs local and file-first have the best chance.

License

• Source code: MIT. See LICENSE.
• Bundled third-party components: listed in THIRD_PARTY_NOTICES.md.
• Screenshots and artwork: not covered by the source license. See assets/screenshots/README.md.