aparta 0.4.4

English | Português (Brasil)

aparta isolates your development accounts, git, GitHub CLI, gcloud, SSH keys, per project folder, and makes your terminal AI agents (Claude Code, Codex, Gemini CLI, Antigravity) use the right identity, always. Aparta is Portuguese for "set apart".

Why aparta?

If you work with more than one identity, a day job, a side gig, freelance clients, open source, you know the drill:

• You commit to a client's repo and only later notice the commit went out with your personal e-mail (or worse: your personal work went out with your employer's e-mail). Rewriting published history is painful; sometimes it's impossible.
• gh and gcloud have one globally active account. Switching in one terminal switches everywhere, including that other terminal where a deploy script was about to run against the wrong project.
• Terminal AI agents inherit whatever identity your shell happens to have. An agent that clones, commits, pushes, or calls cloud APIs on your behalf multiplies the odds of an accident.

The fix is well known among people who've been burned: [includeIf "gitdir:..."] blocks in ~/.gitconfig, parallel gh config directories selected via GH_CONFIG_DIR, named gcloud configurations selected via CLOUDSDK_ACTIVE_CONFIG_NAME, per-host SSH aliases. It works beautifully, but it's tedious to set up by hand, easy to get subtly wrong, and nobody documents how to make AI agents respect it.

aparta automates the whole thing. Folder decides identity. Enter a project under ~/work/acme, and git, gh, gcloud, and your AI agents are the acme you. Enter ~/personal, and they're you-you. No switching, no remembering, no accidents.

How it works

One command, one interactive wizard:

• Scans what you already have, logged-in gh/gcloud accounts, SSH keys and host aliases, existing includeIf blocks, and every git repo on disk grouped by folder and commit e-mail. Existing setups become pre-filled suggestions: confirming a profile is just pressing Enter.
• Or starts from zero, connect a new GitHub account (gh auth login scoped to the profile's own config dir), a new Google account, generate a fresh SSH key (and upload it to GitHub for you).
• Applies safely, every file it touches is backed up first (.bak-aparta-<timestamp>) and merged, never overwritten. --dry-run shows the full diff without changing anything. Nothing ever leaves your machine.
• Verifies, aparta doctor checks the real state: the resolved git e-mail in each repo, gh auth, gcloud config, injected agent env.

Screenshots

The wizard detects your existing setup and pre-fills everything:

One summary, one confirmation, with a safety net:

aparta scan shows what it found without touching anything:

aparta doctor proves each profile is actually working:

Installation

Works on macOS, Linux and Windows through WSL. Requires Python ≥ 3.10. gh and gcloud are optional, aparta selects credentials for the tools you use; it never logs in for you (unless you ask it to, in the wizard).

Recommended: install it as a permanent tool with uv, it is fast, isolated from your projects, and trivial to upgrade:

uv tool install aparta     # recommended
aparta                     # from now on it is just this

Other ways, whatever fits your setup:

uvx aparta            # try it without installing anything
pipx install aparta   # same idea as uv tool, using pipx
pip install aparta    # plain pip, goes into the active environment
npx aparta-cli        # Node ecosystem launcher (needs uv or pipx installed)

Upgrading later: uv tool upgrade aparta (or the equivalent in your chosen tool). Shell autocompletion: aparta --install-completion.

Languages

The CLI speaks English and Brazilian Portuguese. The first run of the wizard asks which one you prefer and remembers it; APARTA_LANG=en or APARTA_LANG=pt overrides the saved choice, and without any of that the locale (LANG) decides.

Quick start

aparta            # first run opens the wizard; later runs open a menu

1. Pick which AI agents should receive per-project environment (Claude Code, Codex, Gemini CLI, Antigravity, or a generic .envrc via direnv).
2. Choose "Detect what I already use" (recommended) or "Start from zero".
3. Confirm each suggested profile, name, folder, git e-mail, SSH key, remote alias, gh account, gcloud account/project all come pre-filled from the scan.
4. Optionally adopt stray repos that live outside your profile folders (they keep their location; identity is applied locally via a git include.path).
5. Review the summary, confirm once. Done.

aparta doctor     # verify everything actually resolves to the right identity
aparta scan       # read-only: show detected project groups
aparta apply X    # re-apply a profile (e.g. after cloning new repos)
aparta list       # list configured profiles
aparta --dry-run  # any command: show diffs, change nothing

What each profile configures

Supported AI agents

Adding a new agent = dropping one file in src/aparta/agents/ (auto-registered).

Safety model

• Every write to an existing file creates a timestamped backup and merges: aparta never overwrites your dotfiles.
• --dry-run previews every change as a diff.
• The scan is 100% read-only.
• Nothing is sent anywhere. No telemetry, no network calls beyond the ones you trigger (gh auth login, gcloud auth login).

Roadmap

• More agents as they gain per-project config support

Works great with

• Orca: an Agent Development Environment that runs several AI agents at once in isolated worktrees, with terminals, editor and browser in one app. Every agent Orca launches inherits the per-folder identity that aparta configured, so parallel agents across different clients stay on the right accounts.
• Universal Memory (U-Mem): a local-first, vendor-agnostic memory layer for AI agents. aparta makes every agent use the right account per folder; U-Mem makes them remember your context and preferences across sessions and tools. Together they cover identity and memory. Keep its .umem/ directory out of version control (this repo's .gitignore already does).

Contributing

Issues and PRs are welcome, see CONTRIBUTING.md. Release history lives in the CHANGELOG.

License

MIT