AgentShell lets several terminal windows use different AI-service logins while they all work in the same real project directory. It changes each tool's state directory; it does not copy the project, change the OS user, or create a container. The commands in this guide work in Bash and Windows PowerShell 5.1 unless an OS-specific block is shown.
This guide uses three example profiles:
personalfor personal worklabfor laboratory workcompanyfor company work
Profile names are labels chosen locally. They may contain letters, numbers, dots, underscores, and hyphens.
AgentShell's --account selects an authentication/state profile:
codex --account personalCodex's native --profile/-p option selects a configuration profile. It does not select a different ChatGPT login. The two concepts are independent.
The AgentShell option must be the first option. Everything after it is passed to the native tool:
# Correct
codex --account lab -m gpt-5.6-sol "Review this repository"
# Incorrect: native Codex receives an unknown --account option
codex -m gpt-5.6-sol --account labPlain commands remain unchanged:
codex
codexr
codexmvRun these from any current directory.
On Bash:
source ~/.bashrc
agentshell personal
codexrOn Windows PowerShell:
. $PROFILE
agentshell personal
codexrThat is the normal workflow. Replace personal with lab or company when needed. Once inside the named shell, plain codex, codexr, and codexmv all use that account.
For the first login only:
codex --account personal login
agent-profile history personal shared
Reload the integration first with source ~/.bashrc on Bash or . $PROFILE on PowerShell.
After login, return to the three-command workflow. Run exit when you want to leave the named AgentShell terminal.
One-shot commands remain available when a dedicated shell is not wanted:
codex --account personal
codexr --account personal
codexr --account personal --allOn a new computer:
cd "$HOME/ProjectsLFS"
git clone https://github.com/lachlanchen/AgentShell.git
cd AgentShell
./install.sh
. "$HOME/.bashrc"No sudo, Docker, or additional OS user is required.
The installer creates:
~/.local/lib/agentshell/agentshell installed runtime
~/.local/bin/agent-* command links
~/scripts/sourced_agent_shell.sh Bash integration
~/.local/share/agentshell/profiles/ account state
Confirm the integration:
type codex
type agentshell
agentshell --helptype codex should report a Bash function after .bashrc is loaded. The function only intercepts a leading --account or --project; otherwise it preserves the normal workstation wrapper.
New-Item -ItemType Directory -Force -Path "$HOME\Projects" | Out-Null
Set-Location "$HOME\Projects"
git clone https://github.com/lachlanchen/AgentShell.git
Set-Location AgentShell
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
. $PROFILENo administrator window, Docker, or additional Windows user is required. The default current-user layout is:
%LOCALAPPDATA%\AgentShell\lib\agentshell.ps1 installed runtime
%LOCALAPPDATA%\AgentShell\bin\*.cmd, *.ps1 command launchers
%LOCALAPPDATA%\AgentShell\shell\agentshell.ps1 PowerShell integration
%LOCALAPPDATA%\AgentShell\profiles\ACCOUNT\ account state
Confirm the integration:
Get-Command codex
Get-Command agentshell
agentshell --helpGet-Command codex should report a PowerShell function after the profile is loaded. The function intercepts only a leading --account or --project; all ordinary invocations continue through the command that was available before AgentShell.
Create as many profiles as needed:
agent-profile create personal
agent-profile create lab
agent-profile create companyCreation is idempotent: running the same command again reuses the profile.
List profiles:
agent-profile listExample output:
ACCOUNT CODEX LOGIN HISTORY STATE
company not logged in shared .../profiles/company
lab not logged in shared .../profiles/lab
personal saved shared .../profiles/personal
Run one login at a time:
codex --account personal login
codex --account lab login
codex --account company loginCodex opens its login flow. In the browser, authenticate with the account intended for that profile. The resulting credential is saved only in that profile's private CODEX_HOME.
This equivalent command is useful when managing profiles:
agent-profile login personal codexIf the callback browser cannot reach the terminal machine, use:
codex --account personal login --device-authFollow the displayed URL and code from any convenient browser.
codex --account personal login status
agent-profile status personal codex
agent-profile listInside a running Codex TUI, /status is the best check for the exact authenticated identity and current session details.
codex --account lab logout
codex --account lab loginThis affects only lab; it does not log out personal, company, or ordinary ~/.codex.
Authentication and the SQLite session index are separate choices.
| Mode | Authentication | Resume index | Best for |
|---|---|---|---|
private |
Profile-local | Profile-local | Confidential separation |
shared |
Profile-local | Shared default Codex index | Resuming the same workstation sessions with several accounts |
New profiles default to private history. Change a profile to shared history with:
agent-profile history personal shared
agent-profile history lab shared
agent-profile history company sharedReturn one profile to private history:
agent-profile history company privateShow the current choice:
agent-profile history company
agentshell status companyIn shared mode:
- credentials remain in the named profile (
~/.local/share/agentshell/profiles/ACCOUNT/codex-home/on Bash or%LOCALAPPDATA%\AgentShell\profiles\ACCOUNT\codex-home\on Windows); - the resume catalog is the default Codex index under
~/.codexon Bash or$HOME\.codexon Windows; codexr --account ACCOUNTcan discover established workstation sessions;- session titles, previews, and paths in that index are visible to every shared profile.
Changing modes does not delete either history. It changes which SQLite location future commands use.
cd /path/to/project
codex --account personalWindows PowerShell equivalent:
Set-Location C:\path\to\project
codex --account personalNative arguments and prompts continue to work:
codex --account lab -m gpt-5.6-sol
codex --account company --search "Review the current repository"
codex --account personal -C /path/to/projectAgentShell prints a short launch banner in an interactive terminal so the selected label is visible before Codex starts.
This is the clearest workflow for long-running work:
cd /path/to/project
agentshell personalThe prompt begins with [agent:personal]. Inside that shell, use normal commands:
agentshell -v
codex
codexr
codexmvThe working directory remains unchanged. On Windows, agentshell ACCOUNT starts a nested PowerShell with the selected account environment; on Bash it starts a nested Bash shell. Exit either dedicated shell with:
exitOpen another terminal and run agentshell lab to use the lab login in the same repository.
Creating lab also creates account-specific command launchers. On Bash they have the following names; Windows exposes the same command names through its installed command directory:
agent-lab-codex
agent-lab-codexr
agent-lab-codexmv
agent-lab-claude
agent-lab-gemini
agent-lab-copilot
These forms are equivalent:
codex --account lab --version
agent-codex --account lab --version
agent-lab-codex --version
agent-run --account lab codex --version--project is an alias for --account:
codex --project labWhen the workstation already has a codexr wrapper, AgentShell preserves it, including its default of sessions whose recorded working directory exactly matches the current directory:
cd /path/to/project
codexr --account personalWindows PowerShell equivalent:
Set-Location C:\path\to\project
codexr --account personalIf no separate codexr command exists, the Windows integration falls back to codex resume. Standard native resume options still work, but workstation-only options such as --non-strict, --include-non-interactive, and --native require the pre-existing wrapper. Use the arrow keys to select, Enter to resume, and q or Ctrl+C to cancel.
Show sessions from every directory:
codexr --account personal --allSearch by a partial directory name:
codexr --account personal --non-strict EchoMindInclude non-interactive runs:
codexr --account personal --all --include-non-interactiveUse Codex's native picker instead of the fast workstation picker:
codexr --account personal --nativeResume the newest native session directly:
codex --account personal resume --lastResume by UUID or a name assigned with /rename:
codex --account personal resume SESSION_ID_OR_NAME--non-strict belongs to codexr, not plain codex:
# Correct
codexr --account personal --non-strict incoder
# Incorrect
codex non-strict incoderIf a project directory was renamed or moved and the workstation provides codexmv, update the indexed session paths with:
codexmv --account personal /old/project/path /new/project/pathOn Windows, quote paths when they can contain spaces:
codexmv --account personal "C:\old project" "D:\new project"This changes Codex session metadata; it does not move project files. The workstation wrapper writes a rollback journal before updating the SQLite rows.
Useful forms:
# Update metadata and resume the newest migrated session
codexmv --account personal --latest /old/path /new/path
# Update metadata without opening Codex
codexmv --account personal --no-resume /old/path /new/path
# Use the native picker after migration
codexmv --account personal --native /old/path /new/pathInside a dedicated AgentShell terminal:
agentshell -vExample:
AgentShell <installed version>
Current account: personal
Codex login: saved
History mode: shared
Codex home: .../profiles/personal/codex-home
SQLite home: <default Codex state directory>
Working dir: <current project directory>
From an ordinary terminal, inspect a named profile explicitly:
agentshell status personal
agent-profile status personal codexagentshell -v in an ordinary shell correctly reports none (ordinary shell). A one-shot child command such as codex --account personal cannot change the parent shell's environment. Its launch banner identifies the selected profile, and /status identifies the authenticated account inside Codex.
Terminal 1, personal work:
source ~/.bashrc
agentshell personal
codexrTerminal 2, lab work:
source ~/.bashrc
agentshell lab
codexTerminal 3, company work:
source ~/.bashrc
agentshell company
codexEvery terminal sees the same filesystem and Git worktrees. Only provider state and authentication are selected by the profile.
Terminal 1, personal work:
. $PROFILE
agentshell personal
codexrTerminal 2, lab work:
. $PROFILE
agentshell lab
codexTerminal 3, company work:
. $PROFILE
agentshell company
codexThe labels are local roles, not account names or email addresses. Every terminal sees the same real Windows project files.
AgentShell also prepares separate state roots for Claude Code, Gemini CLI, and GitHub Copilot CLI:
claude --account lab
gemini --account personal
copilot --account companyOr enter agentshell lab and run the commands without --account. Each provider still requires its own normal login flow. Codex is the most deeply integrated provider on this workstation.
cd "$HOME/ProjectsLFS/AgentShell"
git pull --rebase
./install.sh
. "$HOME/.bashrc"Validate after updating:
agentshell -v
agent-profile list
codex --version
codex --account personal login statusSet-Location "$HOME\Projects\AgentShell"
git pull --rebase
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
. $PROFILEValidate after updating:
agentshell -v
agent-profile list
codex --version
codex --account personal login statusThe current shell has not loaded AgentShell's shell integration, or --account was not first.
On Bash:
. "$HOME/.bashrc"
type codex
codex --account personal login statusNew Bash terminals load the integration automatically.
On Windows PowerShell:
. $PROFILE
Get-Command codex
codex --account personal login statusNew PowerShell terminals load the integration automatically after the installer has added its guarded profile block.
Inspect the profile's history route:
agentshell status personalTo use the established workstation index:
agent-profile history personal sharedA new private profile may have no SQLite database until Codex creates state there. The workstation wrapper falls back to the native picker rather than treating that as corruption.
codexr --account personal --all
codexr --account personal --non-strict PART_OF_OLD_PATHIf a folder was renamed, use codexmv after confirming the old and new paths.
codex --account personal logout
codex --account personal loginThen open Codex and run /status.
codex --account personal login --device-authYou are in an ordinary parent shell. Either inspect a profile explicitly:
agentshell status personalor enter it:
agentshell personal
agentshell -vThis means the picker was cancelled. It does not indicate session-database damage. Run codexr again or use q to leave the picker.
On Bash:
. "$HOME/.bashrc"
printf '%s\n' "$PATH"
ls -l "$HOME/.local/bin/agentshell"If required, rerun ./install.sh; it is designed to be idempotent and refuses to overwrite unrelated commands.
On Windows PowerShell:
. $PROFILE
Get-Command agentshell
$env:Path -split ';'If required, rerun powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\install.ps1. The installer is idempotent and keeps its PowerShell profile integration inside one guarded block.
An EBUSY error naming a Codex executable means Windows still has that npm-installed file open. Finish and exit active Codex CLI, desktop, and IDE sessions, then update from a new PowerShell window. If npm still cannot replace its package tree, use OpenAI's official standalone Windows installer instead of repeatedly retrying the npm update:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
Get-Command codex -All
codex --versionThe official Codex guide lists the standalone installer as the Windows install and update command, with npm as an alternative: Codex CLI installation.
Profile state lives under one of these current-user paths:
Bash: ~/.local/share/agentshell/profiles/ACCOUNT/
Windows PowerShell: %LOCALAPPDATA%\AgentShell\profiles\ACCOUNT\
Important rules:
- Do not upload
auth.json, profile state, cookies, or tokens. - Shared history exposes indexed titles, previews, and paths to every profile using that index.
- AgentShell profiles are not an OS security boundary; all processes still run as the same OS user.
- Use separate OS users or separately controlled machines for mutually untrusted people.
- Prefer browser login. If an account-specific API variable is necessary, use that profile's private environment file rather than a public repository or shared shell profile: mode-0600
env.shon Bash orenv.ps1under the Windows profile directory.
AgentShell deliberately shares authored Codex configuration, skills, plugins, and rules where safe, while keeping provider credentials profile-local.
# Reload integration
. "$HOME/.bashrc"
# Create and inspect profiles
agent-profile create personal
agent-profile list
agentshell status personal
# Login/status/logout
codex --account personal login
codex --account personal login --device-auth
codex --account personal login status
codex --account personal logout
# History mode
agent-profile history personal shared
agent-profile history personal private
# One-shot use
codex --account personal
codexr --account personal
codexr --account personal --all
# Dedicated terminal
agentshell personal
agentshell -v
exit
# Moved project sessions
codexmv --account personal /old/path /new/path
# Update
cd "$HOME/ProjectsLFS/AgentShell"
git pull --rebase
./install.sh
. "$HOME/.bashrc"# Reload integration
. $PROFILE
# Create and inspect profiles
agent-profile create personal
agent-profile list
agentshell status personal
# Login/status/logout
codex --account personal login
codex --account personal login --device-auth
codex --account personal login status
codex --account personal logout
# History mode
agent-profile history personal shared
agent-profile history personal private
# One-shot use
codex --account personal
codexr --account personal
codexr --account personal --all
# Dedicated terminal
agentshell personal
agentshell -v
exit
# Moved project sessions
codexmv --account personal "C:\old path" "D:\new path"
# Update
Set-Location "$HOME\Projects\AgentShell"
git pull --rebase
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
. $PROFILECodex documents CODEX_HOME as the root for config, authentication, logs, sessions, and skills. It separately documents CODEX_SQLITE_HOME for SQLite-backed state. AgentShell uses that supported separation to keep each login private while optionally sharing the resume index: