Share Router

Share Router is a file-first Android share router for turning Android share-sheet input into stable JSON files and route queues.

It receives Android share intents, normalizes the shared content into a JSON payload, classifies the payload as a route kind, writes the latest payload and timestamped queue files under Downloads, and stays fully offline. The app UI remains a simple inspection/control surface for previewing, copying, and re-sharing JSON.

Current release

Current public release: Share Router v1.1.0 Early Access

Release metadata:

• versionCode: 11
• versionName: 1.1.0-early-access
• Android package: com.billybox.sharerouter.projectphone
• internal Gradle lane: projectPhoneDebug

See docs/release-notes-v1.1.0.md.

What it does

Share Router appears in the Android share sheet as Share Router and captures:

• ACTION_SEND
• ACTION_SEND_MULTIPLE
• shared text from Intent.EXTRA_TEXT
• shared subject/title from Intent.EXTRA_SUBJECT
• MIME type
• URI entries from intent.data, Intent.EXTRA_STREAM, and intent.clipData
• best-effort source package/referrer identity

Each share is exported as JSON with route metadata:

• route kinds: link, text, image, file, unknown
• default route queues under routes/<kind>/
• optional custom route targets from config/routes.json
• status.json queue counts and last-received status

File-first export layout

Share Router writes under:

/sdcard/Download/ShareRouter/

Important files and folders:

• latest-payload.json — newest payload, overwritten on every share
• inbox/<timestamp>.json — timestamped payload history
• routes/<kind>/<timestamp>.json — default route queue by classification
• config/routes.json — optional user rules for custom route targets
• status.json — route/inbox/processed/failed queue summary
• processed/ and failed/ — drain script destinations

config/routes.json rules can match by route kind, MIME prefix, text substring, URI substring, source package, or subject substring, and can redirect matching payloads to custom targets under routes/.

Operator scripts

The scripts/ directory contains Termux/operator helpers:

• share-router-status.sh — print queue counts and latest payload info (--json for machine-readable)
• share-router-drain.sh — process inbox/route queue files with a handler or built-in routing (--routes), with --dry-run
• share-router-route.sh — built-in routing engine that dispatches inbox payloads according to config/routes.json rules
• share-router-watch.sh — live inbox monitor that prints new payloads as they arrive (--interval N, --json)
• share-router-clean.sh — safely clean selected queue folders, with --dry-run
• share-router-peek.sh — inspect the latest payload
• share-router-doctor.sh — diagnose setup (folders, permissions, CLI tools, Android package)
• share-router-mcp — optional stdio MCP adapter for agent access (read-only by default, --allow-write-tools for mutations)
• share-router-smoke-text.sh and share-router-smoke-file.sh — local smoke helpers
• make-release-bundle.sh — build the internal Android lane and Gumroad ZIP with checksums and install docs
• validate-contracts.sh — validate local API contract fixtures
• build-termux-deb.sh — build the share-router-tools .deb package

The Termux-side commands are also packaged as share-router-tools. See docs/termux-tools-package.md.

Storage and network permissions

Share Router does not request network permission and is designed to run offline.

The project-phone debug flavor requests MANAGE_EXTERNAL_STORAGE to read shell-created config on Android 13. Other flavors do not require this permission — the app manages its own config in app-specific storage (getExternalFilesDir).

See docs/storage-permission-policy.md for details on the flavor-scoped permission strategy and the path to eliminating broad storage access.

Build

The current internal Android test lane is projectPhoneDebug.

./gradlew assembleProjectPhoneDebug

APK path:

app/build/outputs/apk/projectPhone/debug/app-projectPhone-debug.apk

Install on a connected device:

adb install -r app/build/outputs/apk/projectPhone/debug/app-projectPhone-debug.apk

This lane is an internal Android build target used to produce the Early Access APK.

Payload format

Share Router emits payload schema version 1 with internal payload version currently 2.

{
  "version": 2,
  "schema_version": 1,
  "received_at": "2026-06-15T04:05:45.000Z",
  "action": "android.intent.action.SEND",
  "type": "text/plain",
  "subject": "Example Domain",
  "text": "https://example.com/",
  "uris": [],
  "source_package": "com.android.shell",
  "route": {
    "kind": "link",
    "target": "routes/link",
    "status": "queued"
  }
}

See docs/payload-format.md.

Termux automation export

Example shell share:

am start -W \
  -n com.billybox.sharerouter.projectphone/com.billybox.sharerouter.ShareActivity \
  -a android.intent.action.SEND \
  -t text/plain \
  --es android.intent.extra.SUBJECT "Example Domain" \
  --es android.intent.extra.TEXT "https://example.com/"

cat /sdcard/Download/ShareRouter/latest-payload.json
cat /sdcard/Download/ShareRouter/status.json

See docs/termux-automation-export.md.

Documentation

• docs/share-router-local-api.md — stable local read/write API contract for scripts, CLI tools, and MCP adapters. Documents file layout, JSON schemas, CLI contracts, write safety model, and audit log.
• docs/share-router-mcp.md — optional stdio MCP adapter for agent access to Share Router local state.
• docs/phone-hermes-integration.md — phone Hermes integration contract and runbook.
• docs/storage-permission-policy.md — storage permission policy, flavor scoping, and config path documentation.
• docs/compatibility.md — compatibility and versioning policy for payload, status, CLI, MCP, and audit contracts.
• docs/release-ledger.md — release receipts and artifact provenance ledger.

Verification

Automated coverage includes URI intake tests for intent.data, Intent.EXTRA_STREAM, Intent.EXTRA_STREAM lists, intent.clipData, route classification, custom route rules, status export, and route queues.

Device smoke coverage has passed on the target Android device. v1.1.0 Early Access packaging verification includes unit tests, Android assembly, APK badging checks, script syntax checks, ZIP integrity, and SHA256 checksums.

See also:

• docs/v0.1-finished-checklist.md
• docs/testing-v0.1.md
• docs/termux-automation-export.md

Known limitations

• subject is source-app dependent. Share Router preserves Intent.EXTRA_SUBJECT when provided, but some apps do not send one.
• The project-phone debug flavor uses MANAGE_EXTERNAL_STORAGE for shell-created config on Android 13. Other flavors use app-specific storage and do not require this permission.
• The export file latest-payload.json is overwritten on each new share intent.
• Route targets from config/routes.json must stay under routes/; path traversal targets are ignored.
• The app includes a settings screen (theme, routing config management, live monitoring info) alongside the main share inspection UI.

Maintenance

See MAINTAINERS.md for project structure, conventions, release checklist, and maintenance procedures.

Repository topics

Suggested GitHub topics:

android, kotlin, share-intent, android-sharesheet, intent-router, content-uri, json, offline-first, adb, developer-tools