Using SpeedPy with AI coding agents

An agent that starts from an empty folder hand-rolls authentication, billing and security, and it usually gets them subtly wrong. An agent that starts from SpeedPy inherits production ready rails and only builds your product.

This page lists what SpeedPy already ships for coding agents, and where each file lives.

The short version

Clone SpeedPy, open the project in Claude Code, Cursor or Codex, and start working. The agent reads the conventions on its own, because they are written down in the repository.

bash -c "$(curl -fsSL https://speedpy.com/install)"

AGENTS.md is the source of truth

The repository root holds AGENTS.md. It is a long, specific document, and it is the file agents are meant to read first. It covers:

• the single-app architecture, and the rule that new features extend mainapp rather than creating a new Django app
• the package-style module layout for models, views, forms, admin and tasks, including the re-export conventions
• what belongs in usermodel, what belongs in demoapp, and what belongs in speedpycom
• HTTP API layout, URL conventions, serializer patterns, scopes, tenant isolation and testing requirements
• the webhook extension guide

Two more files exist only as pointers to it:

File	Read by	Contents
AGENTS.md	Codex, and most agents by convention	The full guidance
CLAUDE.md	Claude Code	One line, pointing at AGENTS.md
.cursorrules	Cursor	One line, pointing at AGENTS.md

Keeping the guidance in one file is deliberate. When you change a convention, you change it once, and every agent picks it up.

Your local mode is written down too

Development commands differ between the two setup modes, so the init script writes the right cheat sheet for you:

• bash init-docker.sh copies AGENTS-local.docker.md to AGENTS-local.md
• bash init-local.sh copies AGENTS-local.uv.md to AGENTS-local.md

AGENTS.md tells the agent to read AGENTS-local.md before running anything, so it never has to guess between docker compose run and uv run.

Scoped Cursor rules

.cursor/rules/api.mdc is a path-scoped rule that activates when the agent touches API code, under mainapp/api/, usermodel/api.py, project/api_urls.py, the API tests and the webhook modules. It points back at the API sections of AGENTS.md and adds a short list of quick rules for that area.

Bundled agent skills

SpeedPy ships skills in .agents/skills/, with .claude/skills symlinked to the same directory so Claude Code picks them up without any extra setup.

Skill	What it does
add-integration-api	A numbered recipe for adding a new /api/v1/ resource: model, serializer, views, scopes, URLs, tests, schema, and an optional webhook event
strip-demo	An audit-first workflow for removing the demo and placeholder content from your fork before production. It reads the demo-content.json manifest, searches for SPEEDPY_DEMO markers, produces a removal plan, and waits for your confirmation before changing anything
appliku	Reference for the appliku CLI and Python SDK: authentication, applications, deployments, domains, datastores, servers, teams and SSH keys

strip-demo is worth calling out. Demo content in a boilerplate is useful while you are learning the patterns and embarrassing in production. The skill will not delete anything until you approve the plan.

Let an assistant call your API

Two working examples live in examples/. Both authenticate against a running SpeedPy instance, with either a personal access token or the OAuth2 device flow.

CLI

examples/cli/speedpy_cli.py is a small first party CLI:

export SPEEDPY_TOKEN=spd_...
python speedpy_cli.py me
python speedpy_cli.py teams

It supports login for the device flow, stores credentials in ~/.config/speedpy/config.json, takes --json for machine readable output on every command, and returns distinct exit codes for auth, permission, validation and network failures. That last part matters for agents and for CI, because a script can tell an expired token from an unreachable server.

MCP server

examples/mcp_server/speedpy_mcp.py exposes your API to assistants over the Model Context Protocol.

cd examples/mcp_server
SPEEDPY_TOKEN=spd_... python speedpy_mcp.py

The starter tools are read only:

Tool	Endpoint	Scope
get_current_user	GET /api/v1/me/	read:profile
list_teams	GET /api/v1/teams/	read:teams
list_team_members	GET /api/v1/teams/{id}/members/	read:teams

To wire it into Claude Desktop, add it to claude_desktop_config.json:

{
  "mcpServers": {
    "speedpy": {
      "command": "python",
      "args": ["/path/to/examples/mcp_server/speedpy_mcp.py"],
      "env": {
        "SPEEDPY_API_URL": "http://localhost:8000",
        "SPEEDPY_TOKEN": "spd_your_token_here"
      }
    }
  }
}

Generate MCP tools from your own schema

Rather than hand-maintaining a wrapper per endpoint, generate them from the OpenAPI schema your project already produces:

uv run python manage.py spectacular --file /tmp/speedpy-openapi.yaml --validate
uv run python examples/mcp_server/generate_mcp_tools.py /tmp/speedpy-openapi.yaml \
    -o examples/mcp_server/generated_tools.py

Only GET endpoints are generated. Write operations are skipped on purpose, and --unsafe lists which ones were left out, so nothing destructive is exposed to an assistant by accident. Add --check in CI and the build fails when the checked-in tools drift from the schema.

Full detail for both examples, including Homebrew packaging for the CLI, is in examples/README.md.

If you are building with an agent and do not know Django

This is a supported way to use SpeedPy, not an afterthought.

The parts that are hardest to get right, and most expensive to get wrong, are already done and already tested: email based accounts, two factor authentication, teams and roles, billing, API tokens and scopes, webhooks, background tasks. Your agent does not have to invent them, and you do not have to review them.

A practical sequence that works:

1. Install SpeedPy and get it running locally. See Installation.
2. Open the project in your agent of choice and ask it to read AGENTS.md.
3. Write a short spec for the feature you want, then have the agent implement against that spec rather than against a one line prompt.
4. Run strip-demo before you go to production.
5. Deploy. See Deployment.

Step 3 is the one that decides whether this works, and it is written out in full, prompt by prompt, on Start a project with AI agents.

If you get stuck, ask in the Discord. The boilerplate is free, and questions about it are welcome.

Deploying what your agent built

SpeedPy ships an appliku.yml, so Appliku reads your app, databases and workers from the repository and deploys them to a server you own. The bundled appliku skill means an agent can drive the CLI as well.

You are not tied to it. SpeedPy runs anywhere Django runs, and self-hosting is documented on the Deployment page.