Agent Code

Quick start

python -m pip install agent-code

agent-code

agent-code tui

agent-code doctor

Agent Code requires Python 3.10+. The desktop interface requires Tkinter and CustomTkinter. Browser automation additionally needs a supported Chromium-based browser and its system dependencies.

Installation

Recommended: pip

python -m pip install --upgrade pip
python -m pip install agent-code
agent-code doctor

Ubuntu / Debian

sudo apt update
sudo apt install python3 python3-venv python3-tk podman chromium
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install agent-code

Use the package manager's Chromium package name if your distribution provides a differently named package. Podman is optional unless you want the container sandbox.

Install from source

git clone https://github.com/Agent-code-dev/Agent-code.git
cd Agent-code
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

First run and provider setup

1. Launch agent-code.
2. Open Settings.
3. Select your provider and enter its API key, endpoint and model.
4. Save settings, then send a small test prompt.

Agent Code supports OpenAI-compatible endpoints. Provider-specific login and key setup depend on the provider integration selected in the application. Never paste a secret into a public project file or share a screenshot containing a full key.

Choose a project folder

Launch Agent Code from the project directory you want it to work in. Workspace, chat and project-local files are associated with the selected project. Skills and Add-ons use per-user locations described below.

Everyday workflow

1. Describe the outcome. Include relevant constraints, expected behavior and files if known.
2. Plan first for larger tasks. Use Plan Mode to inspect and propose a sequence before edits; use Build Mode when ready to implement.
3. Watch the concise status. With Activity Details off, the conversation shows the simple Working in project status.
4. Inspect the result. Review changed files, diffs and validation results before accepting the work.
5. Recover if needed. Use the task's recovery point or selective restore controls where available. Review conflicts before restoring.

Ask for tests to be run explicitly when correctness matters. A report must distinguish tests that passed, failed, were skipped, or were not run.

Modes and permissions

Auto mode is not a guarantee that every remote system can be controlled. SSH permissions, host policy, server availability and the selected execution target still apply. Review the command and target before enabling automation.

Activity details, stop and recovery

Activity Details OFF: the chat stays focused on user messages and assistant responses. Internal settings/model/checkpoint logs and detailed task events belong outside the conversation. During work, the compact status is Working in project.

Activity Details ON: use the activity panel to inspect detailed tool and task events, including completion/failure details and recovery information.

Stop: click Stop to request cooperative cancellation. The three-click force-stop gesture requests a stronger cancellation of the agent's work and further AI/tool communication. It is not designed to close the browser application or terminate external browser processes. A currently blocked network call or non-interruptible operation may only stop when its timeout/operation returns.

Recovery: checkpoint capture behavior depends on the files changed during a task. Review the diff and any restore conflict warning before applying a restore.

Skills, MCP and Add-ons are different systems

Do not confuse a Skill with an Add-on: Skills add callable capabilities to the agent; Add-ons extend the host application.

Browser, SSH and sandbox

Browser

Browser automation requires a compatible browser installed on the machine where the browser tool is configured to run. Use browser settings to select or locate the executable when automatic detection fails. A browser session is separate from the agent's AI request loop.

SSH

Configure the remote host and authentication in the SSH connection interface. The remote command permission mode controls whether commands require confirmation. Auto mode should be used only with a trusted host and carefully scoped credentials.

Podman sandbox

The optional Linux sandbox runs commands in an Alpine container. Install and initialize Podman first. The project workspace is mounted for file access; containerization reduces host exposure but does not make untrusted code harmless. Disable sandboxing only when you deliberately want host execution.

Per-skill execution

Do not assume every Skill runs inside the shell sandbox. Skill Python code is loaded by the local Agent Code process unless that Skill itself implements remote execution. Treat installed Skills as trusted local code.

Configuration and data locations

Use agent-code --help for the exact CLI commands available in your installed version. Use agent-code doctor for diagnostics.

Troubleshooting

GUI does not start

• Run agent-code doctor.
• On Ubuntu install Tkinter: sudo apt install python3-tk.
• Check that the active Python environment can import tkinter and customtkinter.

Provider returns 429 / 503 / timeout

Check provider status, model availability, account limits and endpoint configuration. Transient errors may recover after a retry; do not assume a retry succeeded unless Agent Code reports a successful response.

Browser cannot launch

Install a supported Chromium browser, verify the executable path in settings, and run agent-code doctor.

Podman sandbox fails

Check podman info, initialize Podman Desktop/Podman machine where required, and verify that the user can access the Podman service.

Skill or Add-on does not load

Inspect the folder name, entry-point filename, JSON syntax, Python import errors and logs. Reload Skills or restart the app after changing code. Use only code you trust.

Security and trust

• API keys are secrets. Prefer the app's credential/settings mechanism; never commit real keys.
• Skills and Add-ons are Python code and run with the user's permissions. They are not sandboxed merely because Agent Code has a shell sandbox.
• MCP servers may access the resources exposed by their tools. Connect only trusted servers.
• Review shell commands, SSH targets, file diffs and recovery actions.
• Web pages and repository content can contain prompt-injection instructions. Treat external content as data, not as trusted authority.