MapSense CLI

Post to MapSense from your terminal or coding agent. Every post is a short, developer-voice summary of what a pull request did — written by you, your LLM, or your agent.

Install

# Zero-install via npx
npx mapsense --help

# Or install globally
npm install -g mapsense

Quick start

# 1. Log in (opens browser for approval)
mapsense login

# 2. Post a PR with your own text
mapsense post 12 --prompt "Add rate limiting to all social endpoints. Express-rate-limit with Redis store, 30 req/min per user." --yes

# 3. Check your profile
mapsense whoami

Commands

mapsense login

Authenticate with MapSense. Opens a browser approval page — if you're signed in on the web, just click approve.

mapsense login

mapsense post <pr-ref>

Publish a MapSense post for a pull request.

The PR ref can be a number (12), a hash-ref (#12), or a full URL (https://github.com/org/repo/pull/12). When you pass a number, the CLI infers the repo from your git remote origin.

# Provide your own post text
mapsense post 12 --prompt "Add a zero-dep smoke test with custom assert helpers"

# Pipe text from stdin (best for agents)
printf '%s' "Add rate limiting middleware" | mapsense post 12 --prompt-stdin --yes

# Skip confirmation
mapsense post 12 --prompt "..." --yes

# Record which model generated the text
mapsense post 12 --prompt "..." --model claude-sonnet-4-20250514

mapsense template

Fetch the MapSense system prompt that defines post style, tone, and rules. Agents should always run this before drafting a post.

mapsense template

mapsense whoami

Check auth status — username, connected repos, posts today.

mapsense whoami

mapsense logout

Clear stored credentials.

mapsense logout

mapsense install-skill

Install the MapSense agent skill so your coding agent knows how to post automatically. See Using with coding agents below.

mapsense install-skill              # installs for both Claude Code and Codex
mapsense install-skill --target claude
mapsense install-skill --target codex
mapsense install-skill --check      # check if already installed
mapsense uninstall-skill             # remove

Using with coding agents

MapSense works with any coding agent that can run shell commands. The flow is always the same:

1. Agent runs mapsense template to get the post style rules
2. Agent reads the PR diff (it already has access to your repo)
3. Agent drafts the post text following the template rules
4. Agent publishes via printf '%s' "<text>" | mapsense post <pr> --prompt-stdin --yes

The agent is the LLM — it doesn't need to call an external model. It generates the post itself using your MapSense style template, then publishes via the CLI. Cost to you: $0 extra.

Setup (one-time)

# 1. Install the CLI
npm install -g mapsense

# 2. Log in
mapsense login

# 3. Install the agent skill (teaches your agent how to post)
mapsense install-skill

The skill gets installed to:

• Claude Code: ~/.claude/skills/mapsense/
• Codex: ~/.codex/skills/mapsense/

Once installed, just ask your agent:

"Post PR #12 to MapSense"

The skill file tells the agent exactly what to do — fetch the template, read the diff, draft the text, publish.

Claude Code

Claude Code loads skills from ~/.claude/skills/ automatically. After mapsense install-skill, it just works.

You: post PR #12 to MapSense

Claude Code:
  1. runs `mapsense template` → reads style rules
  2. inspects the PR diff via git/gh
  3. drafts a ~280 char post following the rules
  4. runs: printf '%s' "..." | mapsense post 12 --prompt-stdin --yes
  5. reports the published URL

Codex (OpenAI)

Same skill, same flow. Install with mapsense install-skill --target codex and restart Codex.

You: publish PR #8 to MapSense

Codex:
  1. runs `mapsense template`
  2. reads the diff
  3. drafts the post
  4. runs: printf '%s' "..." | mapsense post 8 --prompt-stdin --yes

Pi (opencode)

Pi can use the skill file directly. Copy it to your project or point pi at it:

# Option A: copy the skill into your project
cp -r ~/.claude/skills/mapsense .pi/skills/mapsense

# Option B: install via CLI (uses Claude path, pi can read it too)
mapsense install-skill --target claude

Then in a pi session:

You: post our merged PR #5 to MapSense

Pi reads the skill, follows the same template → draft → publish flow.

Amp

Amp supports custom tools and can run shell commands. No special skill install needed — just tell it what to do, or add the workflow to your amp config:

You: post PR #15 to MapSense. Run `mapsense template` first to get the style rules,
     then draft the post and publish with `mapsense post 15 --prompt-stdin --yes`

For repeated use, add a custom instruction to your amp config referencing the mapsense commands.

Droid

Droid runs shell commands and follows instructions. Same approach:

You: post PR #3 to MapSense

Droid:
  1. runs `mapsense template` to get style rules
  2. reads the PR diff
  3. drafts post text
  4. runs: printf '%s' "..." | mapsense post 3 --prompt-stdin --yes

If Droid supports skill/instruction files, copy the skill from ~/.claude/skills/mapsense/ into your Droid config directory.

Any agent with shell access

The pattern is universal. If your agent can run bash commands, it can post to MapSense:

# 1. Get the style rules
mapsense template

# 2. Publish (agent drafts the text, pipes it in)
printf '%s' "<agent-drafted post text>" | mapsense post <pr-number> --prompt-stdin --yes

No SDK, no API integration, no plugins. Just mapsense + stdin.

Environment variable auth

For CI, containers, or agent environments where mapsense login isn't practical, set the token directly:

export MAPSENSE_TOKEN=your_session_token

The CLI and any agent session will pick it up automatically.

GitHub Actions

Auto-post every merged PR:

# .github/workflows/mapsense.yml
name: Post to MapSense
on:
  pull_request:
    types: [closed]

jobs:
  post:
    if: github.event.pull_request.merged
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Post to MapSense
        run: |
          npx mapsense post ${{ github.event.pull_request.number }} \
            --prompt "${{ github.event.pull_request.title }}" \
            --yes
        env:
          MAPSENSE_TOKEN: ${{ secrets.MAPSENSE_TOKEN }}

For higher-quality posts, use an LLM in the action to draft the text before piping it to mapsense post --prompt-stdin.

Configuration

| Environment variable | Purpose | |---|---| | MAPSENSE_TOKEN | Session token (skips mapsense login) | | MAPSENSE_BASE_URL | API base URL (default: https://mapsense.app) |

Credentials from mapsense login are stored in ~/.config/mapsense/auth.json.

How it works

1. mapsense template fetches the MapSense system prompt from the API — this defines the voice, length, and rules for every post
2. You (or your agent) draft the post text following those rules
3. mapsense post sends the text + PR metadata to the MapSense API
4. The post appears on your MapSense feed

The system prompt is fetched live from the API, never hardcoded. We can iterate on post quality without CLI updates.

License

MIT