LocalSend Transfer Skill for AI coding agents

English | 简体中文

A SKILL.md-compatible skill and cross-platform CLI for sending and receiving files over the local network with LocalSend. The Python package wraps the LocalSend v2 protocol and packages code based on the MIT-licensed localsend-cli.

No cloud account, relay service, or internet connection is required.

Platform support

Role	macOS	Linux	Windows	iOS / Android
Discover devices	✅	✅	✅	Use LocalSend app
Send files	✅	✅	✅	Use LocalSend app
Receive files	✅	✅	✅	✅

The sender/receiver needs Python 3.8+. The cryptography package is installed automatically by pip/pipx/uv and removes the standalone CLI's OpenSSL dependency. Mobile devices only need the normal LocalSend app to receive files.

Install the CLI

pipx (recommended)

pipx install "localsend-codex-skill @ git+https://github.com/qybgh/localsend-codex-skill.git@v0.1.1"

uv

uv tool install "localsend-codex-skill @ git+https://github.com/qybgh/localsend-codex-skill.git@v0.1.1"

pip

macOS / Linux:

python3 -m pip install --user "localsend-codex-skill @ git+https://github.com/qybgh/localsend-codex-skill.git@v0.1.1"

Windows PowerShell:

py -3 -m pip install --user "localsend-codex-skill @ git+https://github.com/qybgh/localsend-codex-skill.git@v0.1.1"

From a local checkout

git clone https://github.com/qybgh/localsend-codex-skill.git
cd localsend-codex-skill
python -m pip install .

Windows PowerShell from a local checkout:

git clone https://github.com/qybgh/localsend-codex-skill.git
cd localsend-codex-skill
.\scripts\install.ps1

After installation, the command is available as:

localsend-transfer --help

Install as an agent skill

Codex

macOS / Linux:

git clone https://github.com/qybgh/localsend-codex-skill.git ~/.codex/skills/localsend-transfer

Windows PowerShell:

git clone https://github.com/qybgh/localsend-codex-skill.git "$env:USERPROFILE\.codex\skills\localsend-transfer"

Or use the bundled installer:

python scripts/install_skill.py --agent codex

Claude Code

User scope:

git clone https://github.com/qybgh/localsend-codex-skill.git ~/.claude/skills/localsend-transfer

macOS PowerShell equivalent:

git clone https://github.com/qybgh/localsend-codex-skill.git "$env:USERPROFILE\.claude\skills\localsend-transfer"

Project scope, run from the target repository:

git clone https://github.com/qybgh/localsend-codex-skill.git .claude/skills/localsend-transfer

Or use the bundled installer:

python scripts/install_skill.py --agent claude-code
# project scope:
python scripts/install_skill.py --agent claude-code --dir .claude/skills/localsend-transfer

Other SKILL.md-compatible agents

If your product supports the SKILL.md convention, copy this repository to its documented global or project skills directory. The core instruction and CLI are not Codex-specific.

CLI-only products

Agents that do not read skills can still use the transfer command after installing the package with pipx, uv, or pip. Then ask or script against:

localsend-transfer discover --json -t 3
localsend-transfer send --to "iPhone" /path/to/file.pdf
localsend-transfer receive --save-dir ~/Downloads/localsend

Command examples

Installed command:

localsend-transfer discover --json -t 3
localsend-transfer send --to "iPhone" /path/to/file.pdf
localsend-transfer receive --save-dir ~/Downloads/localsend

Windows PowerShell path syntax:

localsend-transfer receive --save-dir "$HOME\Downloads\localsend"

Direct IP mode skips discovery:

localsend-transfer send --ip 192.168.5.30 /path/to/file.pdf

Custom advertised name:

localsend-transfer --alias "Work Mac" receive --save-dir ~/Downloads/localsend

Use with an agent

Ask the agent naturally:

Discover LocalSend devices on this network.

Send /path/to/report.pdf to my phone with LocalSend.

Receive a LocalSend transfer into ~/Downloads/localsend.

Running without installing the CLI

From a repository checkout:

python -m localsend_transfer discover --json -t 3

Or use the standalone script:

python scripts/localsend-cli discover --json -t 3

Windows PowerShell:

py -3 -m localsend_transfer discover --json -t 3
py -3 scripts\localsend-cli discover --json -t 3

The package installation installs cryptography; for the standalone script, install it separately or ensure the OpenSSL command-line tool is available.

Updating and removing

pipx:

pipx upgrade localsend-codex-skill
pipx uninstall localsend-codex-skill

pip:

python -m pip install --upgrade "localsend-codex-skill @ git+https://github.com/qybgh/localsend-codex-skill.git@v0.1.1"
python -m pip uninstall localsend-codex-skill

Security notes

• Use this only on trusted local networks.
• Confirm target aliases and paths before sending.
• Do not enable auto-accept on untrusted machines or networks.
• Allow UDP/TCP port 53317, and fallback ports 53318–53319, through your firewall if discovery or transfer fails.

Community

• Linux.do — a friendly developer community. Thanks for the discussions, feedback, and inspiration that support projects like this one.

License

This repository is released under the MIT License. The CLI is based on Chordlini/localsend-cli and remains MIT-licensed; see NOTICE.md and NOTICE.localsend-cli.