English · العربية · Español · Français · 日本語 · 한국어 · Tiếng Việt · 中文 (简体) · 中文（繁體） · Deutsch · Русский

AgentShell

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 Unix users, or maintaining containers. Each process stays in the current directory while provider-supported environment variables route authentication and state into a named profile.

Use in any terminal

This is the normal copy-paste workflow:

source ~/.bashrc
agentshell personal
codexr

It 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:

source ~/.bashrc
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

One folder, several identities

                         same project folder
                    /home/user/Projects/MyApp
                                │
              ┌─────────────────┼─────────────────┐
              │                 │                 │
      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 Unix user; it is not a filesystem or OS security boundary.

Why AgentShell

• Independent authentication: every label has its own Codex auth.json and provider state.
• Optional shared history: accounts may resume one common Codex session index while credentials remain separate.
• 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, and codexmv workflows remain available.
• Provider adapters: Codex is fully integrated; Claude Code, Gemini CLI, and Copilot CLI receive named state roots.
• Safe installation: no root privileges; unrelated commands and profile data are never overwritten.

Quick start

git clone https://github.com/lachlanchen/AgentShell.git
cd AgentShell
./install.sh
. "$HOME/.bashrc"

agent-profile create personal
codex --account personal login
codex --account personal

For a remote/headless login:

codex --account personal login --device-auth

Read the complete tutorial for installation, browser login, account switching, shared/private history, resume, session migration, updates, and troubleshooting.

Three ways to work

Run one account-aware command:

codex --account personal
codex --account lab -m gpt-5.6-sol "Review this repository"
codexr --account company --all

Dedicate a terminal to one account:

cd /path/to/project
agentshell lab

# The prompt now starts with [agent:lab].
agentshell -v
codex
codexr
exit

Or use generated commands:

agent-personal-codex
agent-lab-codexr
agent-company-codexmv /old/path /new/path

The AgentShell --account option must appear first. Plain codex, codexr, and codexmv retain their existing behavior.

Private credentials, selectable history

History mode	Credentials	SQLite resume index	Recommended use
private	Profile-local	Profile-local	Confidential lab/company separation
shared	Profile-local	Shared base index	Resume the same workstation sessions from several accounts

agent-profile history personal shared
agent-profile history company private
agentshell status personal

Codex documents CODEX_HOME as its state root and CODEX_SQLITE_HOME as the location for SQLite-backed state. AgentShell uses that supported boundary; it never shares credentials merely to share a resume catalog.

Account management

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 login

Inside Codex, /status remains the authoritative view of the authenticated identity and running session.

Resume and migrate sessions

# 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/path

The move operation changes only indexed session metadata and writes a rollback journal. It does not move project files.

Supported provider state

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.

Repository map

Path	Purpose
bin/agentshell	Dependency-light profile runtime and command dispatcher
shell/agentshell.bash	Opt-in Bash interception for leading account options
install.sh	Idempotent 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
SECURITY.md	Credential and disclosure guidance

Installation layout

~/.local/lib/agentshell/agentshell       runtime
~/.local/bin/agent-*                     commands
~/scripts/sourced_agent_shell.sh         Bash integration
~/.local/share/agentshell/profiles/      private profile state

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.

Update and validate

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 --check

Security scope

• 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 Unix users, machines, or externally enforced containers for mutually untrusted people.

See SECURITY.md and docs/architecture.md.

Citation

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}
}

Status and license

AgentShell is an actively maintained, dependency-light Bash utility. Codex is the primary verified integration; other provider adapters follow their documented state-directory controls. Licensed under the MIT License.

Links

• Complete tutorial
• GitHub repository
• LazyingArt
• GitHub Sponsors
• Official Codex environment variables