agent-locale

agent-locale helps coding agents run project commands reliably across Unicode paths, shell encodings, Git output, Python launchers, and mixed-encoding files.

It can:

• diagnose local shell, Python, Git, path, and encoding problems;
• create a repository-scoped command gateway;
• save repeatable project commands as aliases;
• verify edits to UTF-8, UTF-16, BOM, and GBK files;
• produce compact local reports for troubleshooting.

Requirements

• Python 3.10 or newer;
• Git;
• Windows, macOS, or Linux.

A coding-agent CLI is optional. The core commands work without Codex, Claude Code, OpenCode, or Gemini CLI.

Install

git clone https://github.com/starsaround/agent-locale.git
cd agent-locale
python -m venv .venv

Activate the environment:

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

Install the CLI:

python -m pip install .
agent-locale --help

Install directly from GitHub without cloning:

python -m pip install "agent-locale @ git+https://github.com/starsaround/agent-locale.git"

On Windows, use py -3 or an absolute interpreter path if python opens the Microsoft Store. On macOS or Linux, use a virtual environment when the system Python rejects package installation.

Quick Start

Inspect the current machine and repository:

agent-locale doctor
agent-locale quickstart

Create the repository-local command gateway:

agent-locale bootstrap
agent-locale repair verify
agent-locale exec -- python --version

List and run saved project commands:

agent-locale commands list
agent-locale run test

Use agent-locale doctor --help for command-specific options, replacing doctor with the command you want to inspect.

Generate the optional harness pack when you need reusable pack files in the current repository:

agent-locale export-pack

Local Files And Cleanup

bootstrap may create:

• .agent-locale/ for gateway state, reports, and command logs;
• .agents/skills/i18n-reliability/ for the managed repository skill;
• a managed block in AGENTS.md.

It does not change global PATH, shell profiles, or system locale settings.

Preview cleanup:

agent-locale clean --all --installed-skill --dry-run
agent-locale deactivate --update-agents --remove-logs --remove-installed-skill --dry-run

Remove --dry-run after reviewing the planned changes.

Agent Integrations

Core diagnosis, gateway, repair, cleanup, and edit verification work without an agent CLI.

Capability	Supported agents
CLI discovery	Codex, Claude Code, OpenCode, Gemini CLI
Task templates and event summaries	Codex, Claude Code, OpenCode
Optional edit-preservation self-test	Codex

Agent-specific adapters are optional. Select one only when generating a task template or running an agent-specific self-test.

Platform Support

Platform	Status
Windows 11	Tested
macOS on Apple silicon	Tested
Linux	Limited
Windows 10	Unverified
macOS on Intel	Unverified

Safety And Privacy

Commands passed to agent-locale exec run with the current user's permissions. Review commands before running them.

Full command logging may contain sensitive output even though common secret formats are redacted. Use one of these modes for sensitive commands:

agent-locale exec --log-policy metadata -- python -V
agent-locale exec --log-policy none -- python -V

Replace python -V with the command you need to run.

Reports, logs, fixtures, and repository state remain local unless you explicitly share or upload them. Review generated files before attaching them to a public issue.

Feedback

Use GitHub Issues for bugs and compatibility feedback. Do not post credentials, private source code, proprietary logs, or other sensitive information.

License

MIT