cursory

Test-run your Python code from your smartphone in the Cursor app

Topics: python · uv · pytest · cursor · ai-agents · template

Minimal install kit that makes an existing Python project Cursor Cloud Agent–ready — so you can ask Cursor (including from your phone) to run scripts and tests against your repo.

You drop this repo into your project as .cursory/ (preferred; hidden kit folder), then install — in a terminal or by asking Cursor. The preferred Cursor flow is: agent shows a plan, asks you in chat what to install, then applies your choices with no bash read prompts — without replacing your pyproject.toml.

Do not gitignore .cursory/. Commit it with your project so teammates and Cloud Agents get the same installer. Still ignore .venv/, caches, and secrets — never the kit itself.

Contents

• Why this exists
• Ask Cursor to run the installer (chat Q&A)
• Ask Cursor to run Python
• What you get
• Prerequisites
• Install
• Installer CLI
• What the installer does
• Templates → destinations
• Rules
• Day-to-day commands
• Adding dependencies
• Secrets
• Cleanup behavior
• Layout after install
• Troubleshooting

Why this exists

Most “agent templates” either:

• assume a greenfield repo and overwrite project files, or
• ship a large dual setup (e.g. Codespaces + agent) you do not need.

cursory is the opposite:

1. Your project already exists (especially its pyproject.toml).
2. You copy only this kit under .cursory/.
3. An installer (or Cursor) asks what is missing and copies only those essentials.
4. Template filenames start with _ so they are never confused with live project files.

That wiring is what lets you open Cursor on a phone or desktop, ask it to run a file, and get real output from your project environment.

Ask Cursor to run the installer (chat Q&A)

Yes — in the Cursor app you can install with natural language. The agent should not drive bash read prompts. Instead it runs a plan → chat Q&A → apply loop.

After this repo lives at your-project/.cursory/, ask something like:

Set up cursory for this project.

Run the cursory installer and ask me what to copy.

What the agent should do

1. Plan — show what exists vs what can be offered:

   ./.cursory/install.sh --plan

2. Ask you in Cursor chat which components to install, for example:
   • create ./cursory.sh? (launcher)
   • copy AGENTS.md? (agents)
   • copy scripts/run-python.sh? (run-python)
   • copy .python-version? (python-version)
   • copy Cursor rules? (cursor-rules)
   • clean underscore templates from .cursory/? (cleanup)
3. Apply your answers (no interactive shell):

   ./.cursory/install.sh --apply --with launcher,agents,run-python,cursor-rules --cleanup

   Or everything still missing:

   ./.cursory/install.sh --apply --all

   Preview first:

   ./.cursory/install.sh --apply --all --dry-run

You say in Cursor	What the agent should do
“Set up cursory / install cursory (ask me)”	--plan, ask in chat, then --apply --with …
“Install everything missing”	--apply --all (includes cleanup) or CURSORY_YES=1 ./.cursory/install.sh
“Install cursory but skip python-version”	--apply --all --without python-version
“Show what cursory would do”	--plan or --apply --all --dry-run

Still true under Cursor:

• Destinations that already exist are not overwritten
• pyproject.toml is never created or overwritten
• The kit folder should be named .cursory (legacy cursory/ still works with a warning; or set CURSORY_TARGET)

Ask Cursor to run Python

After install, you do not need to remember shell commands for routine work — including when you use Cursor from your smartphone.

In Cursor (Cloud Agent or chat with repo tools), you can simply ask:

Run src/hello.py and show me the output.

Run the tests.

Sync dependencies after I edited pyproject.toml.

The agent reads AGENTS.md and is instructed to use:

./scripts/run-python.sh …

instead of bare python / python3 / pip. That wrapper:

• installs uv if needed
• installs the Python version from .python-version when present
• creates .venv and syncs from your pyproject.toml
• then runs the script, module, tests, or sync you asked for

So the normal loop is: write code → ask Cursor (phone or desktop) to run it → read the result.

You can still run the same commands yourself in a terminal; the agent and you share one entrypoint.

Example prompts

You say in Cursor	What the agent should do
“Run src/app.py”	./scripts/run-python.sh src/app.py
“Run src/app.py -- --verbose”	./scripts/run-python.sh src/app.py -- --verbose
“Run the tests”	./scripts/run-python.sh --test
“Sync deps”	./scripts/run-python.sh --sync
“Open a Python REPL”	./scripts/run-python.sh --repl

What you get

Piece	Role
AGENTS.md	Contract the Cloud Agent follows (how to run Python, what not to overwrite)
scripts/run-python.sh	Single entrypoint for run / test / sync / REPL
.python-version	Optional pin (default template: 3.12)
.cursor/rules/python-testing.mdc	Cursor IDE rules for Python/tests
cursory.sh	Optional visible launcher at repo root → .cursory/install.sh

Not installed: a second pyproject.toml, Codespaces/devcontainer stack, or sample app code. Your project stays the source of truth.

Prerequisites

• An existing project directory (ideally already a git repo)
• A project-owned pyproject.toml at the repo root (recommended). The kit will not create or overwrite one.
• Ability to run bash (install.sh, scripts/run-python.sh)
• Network on first uv / Python install (Cloud Agent VMs and fresh machines)

Install

1. Put this kit under your repo as .cursory/

your-project/                 ← your existing repo
  pyproject.toml              ← yours — never overwritten
  src/                        ← yours
  tests/                      ← yours
  .cursory/                   ← copy or clone of this repository (preferred name)
    install.sh
    _AGENTS.md
    _run-python.sh
    _python-version
    _python-testing.mdc
    README.md

Clone example:

cd your-project
git clone https://github.com/kazuyamagiwa/cursory.git .cursory

Or copy the folder in and name it exactly .cursory.

Git tip: do not add .cursory/ to .gitignore. Track the kit in git. Keep ignoring .venv/, __pycache__/, logs, and secrets only.

2. Run the installer

Option A — ask Cursor with chat Q&A (recommended):

Set up cursory and ask me what to install.

→ --plan → questions in chat → --apply --with …
See Ask Cursor to run the installer (chat Q&A).

Option B — install everything missing (no questions):

./.cursory/install.sh --apply --all
# same as:
CURSORY_YES=1 ./.cursory/install.sh

Option C — terminal interactive Q&A (real TTY only; not for agents):

./.cursory/install.sh

The kit directory should be named .cursory (legacy cursory/ is accepted with a warning; or set CURSORY_TARGET).

Installer CLI

./.cursory/install.sh --help
./.cursory/install.sh --scan          # report what exists / is missing
./.cursory/install.sh --plan          # scan + offer list for chat Q&A
./.cursory/install.sh --apply --all   # install every missing component + cleanup
./.cursory/install.sh --apply --all --dry-run
./.cursory/install.sh --apply --with launcher,agents,run-python --cleanup
./.cursory/install.sh --apply --all --without python-version

Component id	Effect
launcher	Create ./cursory.sh → .cursory/install.sh
agents	_AGENTS.md → AGENTS.md
run-python	_run-python.sh → scripts/run-python.sh
python-version	_python-version → .python-version
cursor-rules	_python-testing.mdc → .cursor/rules/python-testing.mdc
cleanup	Remove installed underscore templates (and safe leftovers) from .cursory/

CURSORY_YES=1 with no args is an alias for --apply --all --cleanup.

What the installer does

your-project/   ← TARGET (parent of .cursory/)
.cursory/       ← KIT (this repo)

1. Resolve target — parent of .cursory/ (or CURSORY_TARGET)
2. Scan / plan — report what exists; list components you can still install
3. Apply — create launcher and/or copy selected _ templates (underscore removed)
4. Cleanup (optional) — remove used _ templates from the kit when their destination already exists at repo root

Templates → destinations

All templates in this kit must start with _.

Template in .cursory/	Copied to (repo root)
_AGENTS.md	AGENTS.md
_run-python.sh	scripts/run-python.sh
_python-version	.python-version
_python-testing.mdc	.cursor/rules/python-testing.mdc

If the destination already exists, that file is left untouched.

Rules

• Never overwrite existing destinations
• Never create or overwrite pyproject.toml (project-owned)
• Prefer kit folder name .cursory/ (not cursory/)
• Do not gitignore .cursory/ — commit the kit; ignore .venv and caches instead
• Templates in this kit must be named with a leading _
• Agents: use --plan + chat Q&A + --apply (not interactive read)
• Agents and humans should run Python via ./scripts/run-python.sh, not bare python3
• Do not commit API keys; use Cursor environment secrets

Day-to-day commands

Prefer asking Cursor (see Ask Cursor to run Python). Equivalent terminal commands:

# Run a script
./scripts/run-python.sh path/to/script.py
./scripts/run-python.sh path/to/script.py -- --flag value

# Tests
./scripts/run-python.sh --test
./scripts/run-python.sh -m pytest tests/ -v

# Sync after editing pyproject.toml
./scripts/run-python.sh --sync

# REPL
./scripts/run-python.sh --repl

Adding dependencies

1. Edit your pyproject.toml (add to dependencies or optional groups).
2. Ask Cursor to sync, or run:

./scripts/run-python.sh --sync

Do not replace pyproject.toml with anything from this kit.

Secrets

Never commit real API keys.

• Store secrets as Cursor environment secrets for Cloud Agent runs.
• Read them in code with os.environ["YOUR_KEY_NAME"].
• The name may appear in docs/code; the value must not appear in git.

Cleanup behavior

After apply, optional cleanup deletes unnecessary files inside .cursory/:

Kind	Behavior
Underscore templates (_AGENTS.md, …)	Removed when cleanup runs and the destination already exists at repo root; unselected templates are kept for later
Other kit leftovers (README.md, old src/, …)	Removed only if the same name already exists at the repo root
install.sh	Always kept so you can re-run

Re-run anytime:

./cursory.sh --plan
# or
./.cursory/install.sh --plan

Existing project files are still never overwritten.

Layout after install

Typical result:

your-project/
  pyproject.toml                 ← unchanged (yours)
  AGENTS.md                      ← from _AGENTS.md
  cursory.sh                     ← optional root launcher → .cursory/install.sh
  .python-version                ← optional
  scripts/
    run-python.sh                ← from _run-python.sh
  .cursor/rules/
    python-testing.mdc           ← from _python-testing.mdc
  .cursory/
    install.sh                   ← kept
    README.md                    ← kept if not also at repo root
    …                            ← underscore templates removed if cleanup ran
  src/ …                         ← yours
  tests/ …                       ← yours

Troubleshooting

Problem	What to do
This kit must live at <your-repo>/.cursory/	Rename the folder to .cursory, or set CURSORY_TARGET
Agent tries interactive read prompts	Tell it to use --plan then --apply; or --apply --all
Interactive prompts require a TTY	Expected for agents — use --apply flags instead of bare ./install.sh
Agent uses system python3	Ensure AGENTS.md was installed; ask it to follow AGENTS.md / use ./scripts/run-python.sh
uv sync fails	Fix your pyproject.toml / build backend; the kit does not own that file
Script runs but prints nothing	Many modules only define functions — ask Cursor to call an entrypoint or add a __main__ block
Want a file the installer skipped	Re-run with --apply --with <id>; still will not overwrite existing destinies
First run is slow	Normal: uv and CPython may download once, then be cached
.cursory missing after clone	Make sure it is not listed in .gitignore and was committed

License

See LICENSE.