agent-code

Agent + Skill Store

A local AI agent with a headless browser, sandboxed shell, chat GUI, and a plug-and-play skill system backed by a hosted skill registry.

Live site: https://agent-code.freesrv.com · Install: pip install agent-code

---

What this is

One command install. Two GUIs. A hosted skill registry.

Skills are folders under ./skills/. Drop one in, restart the agent, its tools appear in the LLM's tool list. No changes to the agent required.

---

Install

pip install agent-code

That's it. No clone, no config file, no build step.

Then:

agent-code              # run the agent
agent-code manage       # open the skill store
agent-code skills       # list bundled skills
agent-code skills install   # copy them into ./skills/

First run

The agent needs an API key. On first launch:

1. Click Settings in the top-right of the agent window
2. Paste your API key
3. Optionally change the base URL and model
4. Save

Or create agent_config.json in the folder where you run the agent:

{
  "openai_api_keys": ["sk-your-key-here"],
  "openai_base_url": "https://api.openai.com/v1",
  "openai_model": "gpt-4o",
  "cloud_sync": false
}

The config file wins if both exist. The Settings dialog writes to it.

Talk to it

go to news.ycombinator.com and list the top 5 story titles
find a free API for cat facts and call it
create a snake game in a single HTML file

---

Platform support

Linux setup

One line per distro — installs tkinter (GUI) and Chromium (browser):

# Ubuntu / Debian / Kali / Mint / Pop!_OS
sudo apt install python3-tk chromium

# Fedora / RHEL / CentOS Stream
sudo dnf install python3-tkinter chromium

# Arch / Manjaro
sudo pacman -S tk chromium

If agent-code isn't found after install, add pip's user bin to PATH:

export PATH="$HOME/.local/bin:$PATH"

Or use the module form which never needs PATH:

python3 -m agent_code --version
python3 -m agent_code run

Windows setup

pip install agent-code handles the Python side. If agent-code run shows browser: FAILED, install the WebView2 Runtime from Microsoft. It's preinstalled on Windows 11 and most up-to-date Windows 10.

---

The skill system

A skill is a folder:

skills/my_skill/
├── skill.py     ← code
└── skill.md     ← metadata + docs

skill.py exports three things:

SKILL = {"name": "my_skill", "description": "What this does."}

def greet(name: str = "world") -> str:
    return f"Hello, {name}!"

TOOL_SCHEMAS = [{
    "type": "function",
    "function": {
        "name": "greet",
        "description": "Return a greeting.",
        "parameters": {
            "type": "object",
            "properties": {"name": {"type": "string"}},
        },
    },
}]

TOOL_CALLABLES = {"greet": greet}

Restart the agent. The LLM can now call greet().

Optional COMMANDS export adds user-facing slash commands:

def _handle_ping(args: list, log) -> None:
    log(f"pong {' '.join(args)}", "dim")

COMMANDS = {
    "ping": {"handler": _handle_ping, "description": "Reply pong"},
}

Optional skill.md frontmatter gives the skill a name, version, and author. Anything after the closing --- becomes the skill's help page, visible in the Help dialog when the user clicks the skill.

Full developer guide: read the module docstring in src/agent_code/loader.py — the loader is ~200 lines and documents the whole skill contract.

---

Bundled skills

pip install agent-code ships three skills. Run agent-code skills install to copy them into your current folder's skills/:

Installed skills appear under ./skills/<name>/ with skill.py and skill.md. Toggle them on/off in the Skills dialog.

---

Skill registry

The registry lets you publish skills and install them anywhere.

Use the hosted registry (default)

A live instance is already running at https://skills-manager.freesrv.com. Both the manager and the agent use it by default. If the domain is down, they auto-fall-back to a raw IP.

agent-code manage

Sign in with any nickname — the account is created automatically. Then:

• Browse and search the store
• Install skills into ./skills/
• Publish a folder as a skill
• Delete skills you own

Self-hosting the registry

The server is GPL-3.0 and lives in this repo as skill-server.py. See Server setup below.

---

Command reference

CLI

Agent (in the chat box)

Agent buttons

---

Configuration reference

agent_config.json

Placed in the folder where you run agent-code, or in the platform config dir if no local file exists:

• Windows: %APPDATA%\agent-code\agent_config.json
• Linux/macOS: ~/.config/agent-code/agent_config.json

{
  "openai_api_keys": ["sk-...", "sk-..."],
  "openai_base_url": "https://api.openai.com/v1",
  "openai_model": "gpt-4o",
  "cloud_sync": false,
  "disabled_skills": [],
  "email_api": {
    "provider": "resend",
    "api_key": "re_...",
    "from_addr": "onboarding@resend.dev",
    "from_name": "Agent"
  }
}

Where files go

When you run agent-code from a folder, it creates:

<your-folder>/
├── skills/          ← installed + bundled skills
├── workspace/       ← sandbox for shell and file tools
├── chats/           ← auto-saved conversation
└── agent_config.json (if you created one here)

Whichever folder you launch from is the "project" for that session. Run agent-code from different folders to keep separate projects.

---

Server setup

Only needed if you want your own registry instance. The client works with the hosted one out of the box.

mkdir -p /opt/skill-server && cd /opt/skill-server
# copy skill-server.py here
python3 skill-server.py --host 0.0.0.0 --port 8000

Then point the clients at it by editing SKILL_SERVER_PRIMARY and SKILL_SERVER_FALLBACK in the source, or by setting them in agent_config.json.

---

Security

The agent executes LLM-generated commands. That's the point, but it means you need to be careful.

Already sandboxed:

• Shell — allowlist of commands, shell=False, CWD=workspace/, no pipes / redirects / ; / & / &&, no absolute paths outside the workspace
• Filesystem skill — every path resolved and validated against workspace/
• Browser — headless, in a throwaway profile
• Registry server — PBKDF2 password hashing, session tokens, ownership checks on publish/delete, ZIP entry validation, upload size cap

Not sandboxed:

• python is in the shell allowlist — the agent can read arbitrary files. Remove python, python3, node from ALLOWED_CMDS if that matters.
• curl / wget are allowed — the agent can POST local data to remote servers.
• Skills are arbitrary Python — installing a skill is trusting its author.
• Prompt injection via web content — a malicious page can steer the agent.

For untrusted use, run the agent inside Docker.

---

Files at a glance

Installed package

site-packages/agent_code/
├── __init__.py
├── __main__.py
├── cli.py
├── paths.py
├── agent.py
├── skill_manager.py
├── loader.py
└── data/
    └── skills/
        ├── filesystem/{skill.py,skill.md}
        ├── public_api/{skill.py,skill.md}
        └── temp_mail/{skill.py,skill.md}

Your project folder (created on first run)

your-folder/
├── skills/
├── workspace/
├── chats/
└── agent_config.json (optional)

This repository

Agent-code/
├── pyproject.toml          ← PyPI metadata
├── src/agent_code/         ← the package source
├── docs/skills.html        ← developer guide
├── README.md
├── LICENSE                 ← MIT
├── LICENSE-GPL             ← GPL-3.0
└── .gitignore

skill-server.py (the registry backend, GPL-3.0) is deployed separately on a VPS.

---

Troubleshooting

---

Development

Clone the repo, install in editable mode:

git clone https://github.com/minecraftbefile-maker/Agent-code.git
cd Agent-code
pip install -e .

Run the agent, manager, and site server directly:

agent-code run
agent-code manage
python -m agent_code.landing --port 8080     # if you kept the site server

The skill loader is ~200 lines: src/agent_code/loader.py. Read it alongside docs/skills.html — between the two you'll know everything the agent does with a skill.

---

License

Split license:

Why the split? The client code is meant to be embedded, forked, and redistributed freely. The server is meant to stay open — if you host a modified version, you must publish your changes.

Default skills use third-party services:

• mail.tm — receive-only temp inbox, no signup
• Guerrilla Mail — fallback inbox
• Resend / Brevo / Mailjet — email sending, free tiers
• public-api-lists — public API catalog (MIT)
• DrissionPage — browser automation (BSD-3)
• OpenAI Python SDK — LLM client (Apache-2.0)