Metadata-Version: 2.4
Name: agent-locale
Version: 0.1.0a1
Summary: Reliable coding-agent commands across Unicode paths, shell encodings, Git output, Python launchers, and mixed-encoding files.
Author: agent-locale contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/starsaround/agent-locale
Project-URL: Repository, https://github.com/starsaround/agent-locale
Project-URL: Issues, https://github.com/starsaround/agent-locale/issues
Keywords: coding-agents,agent-tools,unicode,locale,i18n,cjk,windows,codex,claude-code,opencode,gemini-cli,agents-md
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Shells
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: PyYAML<7,>=6.0; extra == "dev"
Requires-Dist: ruff<1,>=0.8; extra == "dev"
Dynamic: license-file

# 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

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

Activate the environment:

```bash
# macOS / Linux
source .venv/bin/activate
```

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

Install the CLI:

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

Install directly from GitHub without cloning:

```bash
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:

```bash
agent-locale doctor
agent-locale quickstart
```

Create the repository-local command gateway:

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

List and run saved project commands:

```bash
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:

```bash
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:

```bash
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:

```bash
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](LICENSE)
