# Quarters

> Gives a shell its own configuration, history and credentials, on the same account.

- **Status:** Alpha — v0.1.0-alpha.2
- **Year:** 2026
- **Implementation:** Rust, macOS + Linux
- **Repository:** https://github.com/Agenxy/quarters
- **Repository facts:** Apache-2.0, 1 stars, 0 forks, last pushed 2026-08-21T21:35:49Z

## Project pages

- [Architecture](https://agenxy.org/projects/quarters/architecture/): How Quarters redirects user state while keeping the host account and native process model.

---

Command-line tools usually keep user state below `HOME`. Every session then
shares one shell history, one Git identity and one set of credentials.

Quarters gives a native process tree a named, persistent home. Compatible
tools read and write their state there. The process continues to use your Unix
account and the machine's native programs, files, network and devices.

## Basic use

```text
$ quarters create work
Created work
...
$ quarters exec work -- quarters current
work
$ quarters enter work
```

Inside that shell, global Git config and shell history belong to `work`. Each
space persists after its shell exits. `quarters exec work -- COMMAND` runs one
command in a space. From a space entered without Linux `--home-view`,
`quarters host -- COMMAND` runs one command with the host state paths.

## What moves

Quarters sets `HOME`, the XDG roots, shell startup and history paths, and
supported paths for Git, GitHub CLI, GnuPG, tmux, Cargo, npm and uv. It also
routes Codex, Claude Code and OpenCode state where those tools provide a usable
environment contract.

The child environment starts from a small allowlist. Extra variables are
included only when named with `--inherit`; diagnostic output redacts their
values.

## Where it stops

Quarters separates user state. It is not a security boundary. UID, groups,
filesystem permissions, `sudo`, the kernel, devices, network and login session
remain those of the host account. Absolute paths can still reach the real
home. macOS Keychain, TCC and app containers stay host-bound.

By default, macOS and Linux use environment variables to route state. macOS
also sets `CFFIXED_USER_HOME` as a best-effort compatibility aid. Linux can add
an opt-in mount-namespace home view only when the account has no supplementary
groups and the host allows unprivileged user namespaces. `quarters doctor`
reports the exact platform and tool gaps.

## Install the alpha

Install from one of the published channels:

- Homebrew: `brew install agenxy/tap/quarters`
- Cargo: `cargo install --locked --version 0.1.0-alpha.2 quarters`
- npm: `npm install --global quarters-cli@alpha`

The npm macOS executables are unsigned and unnotarised in this alpha. Homebrew
or Cargo builds locally when host policy rejects them.

## Copying spaces

Copy commands remain absent because a live copy can capture database
write-ahead logs, sockets, agent state or partial writes.

Source: https://agenxy.org/projects/quarters/