English · العربية · Español · Français · 日本語 · 한국어 · Tiếng Việt · 中文 (简体) · 中文（繁體） · Deutsch · Русский
Named AI CLI accounts for separate terminals, sharing one real working tree.
AgentShell lets personal, laboratory, and company terminals use different Codex logins without copying projects, changing OS users, or maintaining containers. Each process stays in the current directory while provider-supported environment variables route authentication and state into a named profile. Bash and Windows PowerShell are supported.
On Bash:
source ~/.bashrc
agentshell personal
codexrOn Windows PowerShell:
. $PROFILE
agentshell personal
codexrIt works from whichever directory that terminal is already using. Replace personal with lab or company when needed.
Only the first login needs two extra commands; these are identical in both shells:
codex --account personal login
agent-profile history personal shared
Inside agentshell personal, plain codex, codexr, and codexmv all use that account. Run exit when finished.
| Donate | PayPal | Stripe |
|---|---|---|
 |
 |
 |
The official ChatGPT Linux preview includes Codex. Install it, then use these launchers to reuse your AgentShell logins in separate desktop windows. Reopening an account reuses its existing app.
agent-desktop --install-launchers company personal lab
agent-desktop company
agent-desktop personal
agent-desktop labInstallation, login, APT updates, and isolation details.
same project folder
<project directory>
│
┌─────────────────┼─────────────────┐
│ │ │
terminal: personal terminal: lab terminal: company
│ │ │
personal login lab login company login
└─────────────────┴─────────────────┘
shared real files
AgentShell is intentionally lighter than Docker. It separates application state for trusted accounts owned by one OS user; it is not a filesystem or OS security boundary.
- Independent authentication: every label has its own Codex
auth.jsonand provider state. - Shared history by default: new accounts resume the workstation Codex index and rollout tree while credentials remain separate; private history is available explicitly.
- No workspace copies: Git repositories, Conda environments, build tools, and files stay exactly where they are.
- Native arguments preserved: models, prompts, sandbox options, search, images, and future CLI flags pass through.
- Fast workstation resume: existing
codexr,/rename, partial-path search, andcodexmvworkflows remain available. - Provider adapters: Codex is fully integrated; Claude Code, Gemini CLI, and Copilot CLI receive named state roots.
- Safe installation: no root or administrator privileges; unrelated commands and profile data are never overwritten.
git clone https://github.com/lachlanchen/AgentShell.git
cd AgentShell
./install.sh
. "$HOME/.bashrc"
agent-profile create personal
codex --account personal login
codex --account personalgit clone https://github.com/lachlanchen/AgentShell.git
Set-Location AgentShell
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
. $PROFILE
agent-profile create personal
codex --account personal login
codex --account personalFor a remote/headless login:
codex --account personal login --device-authRead the complete tutorial for installation, browser login, account switching, shared/private history, resume, session migration, updates, and troubleshooting.
Run one account-aware command:
codex --account personal
codex --account lab -m gpt-5.6-sol "Review this repository"
codexr --account company --allDedicate a terminal to one account:
cd /path/to/project # Bash
Set-Location C:\path\to\project # Windows PowerShell
Then enter the account shell:
agentshell lab
# The prompt now starts with [agent:lab].
agentshell -v
codex
codexr
exitOr use generated commands:
agent-personal-codex
agent-lab-codexr
agent-company-codexmv /old/path /new/pathThe AgentShell --account option must appear first. Plain codex, codexr, and codexmv retain their existing behavior.
| History mode | Credentials | SQLite resume index | Rollout tree | Recommended use |
|---|---|---|---|---|
private |
Profile-local | Profile-local | Profile-local | Confidential lab/company separation |
shared |
Profile-local | Shared base index | Shared base tree | Resume the same workstation sessions from several accounts |
agent-profile history personal shared
agent-profile history company private
agentshell status personalCodex documents CODEX_HOME as its state root and CODEX_SQLITE_HOME as the location for SQLite-backed state. AgentShell keeps account authentication under the profile while a generated shared-history view links only the history-bearing paths to the common Codex tree. This matters for current Codex releases because paginated sessions locate source rollouts through CODEX_HOME/sessions, not through SQLite alone.
New accounts default to shared history and can find the same current-folder sessions as ordinary Codex. Existing accounts keep their configured mode, so an older private account can still hide workstation sessions. To locate saved sessions, run:
agent-profile sessions companyThis read-only report lists the base, configured shared, and private account stores with rollout file counts, including archived files. Counts include agent threads and may differ from the picker. It does not read credentials or conversation contents. Run it separately in WSL and Windows to inspect each installation's stores.
To continue your existing workstation sessions using the company account's login:
agent-profile history company shared
agent-codex --account company resume --allThe selected account keeps its credentials; history is shared with other profiles that opt into the same store. Existing private sessions stay in their original directory and can be reached by switching back to private. Running Codex processes keep their current history route; launch a new account command after changing modes. Avoid manually setting CODEX_HOME to the base home when you want to retain the company login, because that also selects the base account's credentials.
agent-profile create lab
agent-profile list
agent-profile show lab
agent-profile status lab codex
agent-profile login lab codex
agent-profile aliases lab
codex --account lab login status
codex --account lab logout
codex --account lab loginInside Codex, /status remains the authoritative view of the authenticated identity and running session.
AgentShell preserves existing workstation codexr and codexmv wrappers. Without a separate resume wrapper, codexr falls back to codex resume, preserving native current-directory filtering. Use codexr --all to show other project directories, including when launching from ~ or ~/Projects; workstation-only picker flags and codexmv require pre-existing wrappers.
Directory scope and account history are separate. To show the ordinary workstation history with each existing account, enable sharing for each one, then reopen its shell:
agent-profile history personal shared
agent-profile history lab shared
agentshell lab
codexrAccount logins remain separate. New profiles use shared history automatically. To isolate a profile's sessions, run agent-profile history ACCOUNT private. Already-running shells retain their old history environment until reopened. Account registration is idempotent and does not reset an existing history choice.
# Exact current directory
codexr --account personal
# All directories or partial-path search
codexr --account personal --all
codexr --account personal --non-strict ProjectName
# Update stored cwd metadata after moving a project
codexmv --account personal /old/project/path /new/project/pathThe move operation changes only indexed session metadata and writes a rollback journal. It does not move project files.
| Provider | Profile routing | Example |
|---|---|---|
| Codex | CODEX_HOME, CODEX_SQLITE_HOME |
codex --account lab |
| Claude Code | CLAUDE_CONFIG_DIR |
claude --account lab |
| Gemini CLI | GEMINI_CLI_HOME |
gemini --account personal |
| GitHub Copilot CLI | COPILOT_HOME, COPILOT_CACHE_HOME |
copilot --account company |
Provider details and limitations are documented in docs/providers.md.
| Path | Purpose |
|---|---|
| bin/agentshell | Dependency-light profile runtime and command dispatcher |
| bin/agentshell.ps1 | Windows PowerShell profile runtime and command dispatcher |
| shell/agentshell.bash | Opt-in Bash interception for leading account options |
| shell/agentshell.ps1 | PowerShell interception and account-shell integration |
| install.sh | Idempotent current-user installer |
| install.ps1 | Idempotent Windows current-user installer |
| docs/tutorial.md | Complete start-to-finish tutorial |
| docs/architecture.md | State boundaries, inheritance, and safety design |
| docs/providers.md | Codex, Claude, Gemini, and Copilot adapters |
| tests/test.sh | Isolated integration tests |
| tests/test.ps1 | Windows PowerShell 5.1 integration tests |
| SECURITY.md | Credential and disclosure guidance |
~/.local/lib/agentshell/agentshell runtime
~/.local/bin/agent-* commands
~/scripts/sourced_agent_shell.sh Bash integration
~/.local/share/agentshell/profiles/ private profile state
ACCOUNT/codex-home/ private-mode and legacy account state
ACCOUNT/codex-shared-home/ shared-mode account/history view
On Windows, the default current-user layout is:
%LOCALAPPDATA%\AgentShell\lib\agentshell.ps1 runtime
%LOCALAPPDATA%\AgentShell\bin\*.cmd, *.ps1 command launchers
%LOCALAPPDATA%\AgentShell\shell\agentshell.ps1 PowerShell integration
%LOCALAPPDATA%\AgentShell\profiles\ private profile state
ACCOUNT\codex-home\ private-mode and legacy state
ACCOUNT\codex-shared-home\ shared-mode account/history view
AgentShell keeps HOME, PWD, Git credentials, and the real filesystem unchanged. Authored settings and skills may be inherited, but known provider credentials and histories are never copied into a new profile.
cd "$HOME/ProjectsLFS/AgentShell"
git pull --rebase
./install.sh
. "$HOME/.bashrc"
bash -n bin/agentshell shell/agentshell.bash install.sh tests/test.sh
bash tests/test.sh
git diff --checkWindows PowerShell update and validation:
Set-Location "$HOME\Projects\AgentShell"
git pull --rebase
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
. $PROFILE
agentshell -v
agent-profile list
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\tests\test.ps1
git diff --check- Never commit profile homes,
auth.json, tokens, cookies, SQLite databases, or private environment files. - Shared history intentionally exposes indexed session titles, previews, and paths to each participating profile.
- Inherited API-token variables are cleared unless a profile explicitly opts in.
- Use separate OS users, machines, or externally enforced containers for mutually untrusted people.
See SECURITY.md and docs/architecture.md.
If you use AgentShell in research or tooling, cite the repository. GitHub reads CITATION.cff and shows a Cite this repository panel on the repository page.
@software{chen_agentshell_2026,
author = {Chen, Lachlan},
title = {AgentShell: Named AI CLI Account Profiles for Shared Working Trees},
year = {2026},
url = {https://github.com/lachlanchen/AgentShell}
}AgentShell is an actively maintained, dependency-light Bash and Windows PowerShell utility. Codex is the primary verified integration; other provider adapters follow their documented state-directory controls. Licensed under the MIT License.