npm package: @metmirr/mapsense
Description: CLI for publishing MapSense posts from pull requests
Latest version: 0.0.4

# MapSense CLI

Post to [MapSense](https://mapsense.app) 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

```bash
# Zero-install via npx
npx mapsense --help

# Or install globally
npm install -g mapsense
```

## Quick start

```bash
# 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.

```bash
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`.

```bash
# 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.

```bash
mapsense template
```

### `mapsense whoami`

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

```bash
mapsense whoami
```

### `mapsense logout`

Clear stored credentials.

```bash
mapsense logout
```

### `mapsense install-skill`

Install the MapSense agent skill so your coding agent knows how to post automatically. See [Using with coding agents](#using-with-coding-agents) below.

```bash
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)

```bash
# 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](https://github.com/mariozechner/pi-coding-agent) can use the skill file directly. Copy it to your project or point pi at it:

```bash
# 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](https://ampcode.com) 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](https://droid.dev) 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:

```bash
# 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:

```bash
export MAPSENSE_TOKEN=your_session_token
```

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

## GitHub Actions

Auto-post every merged PR:

```yaml
# .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