/agent-instagram

name: agent-instagram
description: Interact with Instagram DMs - send messages, read conversations, manage accounts
version: 2.38.0
allowed-tools: Bash(agent-instagram:*)
metadata:
  openclaw:
    requires:
      bins:
        - agent-instagram
    install:
      - kind: node
        package: agent-messenger
        bins: [agent-instagram]

Agent Instagram

An Instagram DM CLI for AI agents. Supports browser cookie extraction (zero-config, extracts from Chromium browsers) and username/password authentication (with 2FA). Uses Instagram's private mobile API to read and send direct messages.

Use one of these entrypoints:

• Global install: `agent-instagram ...`
• One-off execution: `bunx --package agent-messenger agent-instagram ...`

Key Concepts

• **Thread ID** = Instagram's identifier for a DM conversation. Numeric string returned by `chat list`.
• **Browser cookie extraction** = recommended auth method. Extracts cookies from Chromium browsers (Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium) where you're logged into instagram.com. Zero-config.
• **Username/password auth** = fallback method. Authenticates using Instagram credentials. Supports two-factor authentication via SMS or authenticator app.
• **HTTP-based** = each CLI command makes HTTP requests and returns. No persistent connection or background process. The SDK additionally offers real-time listeners (`InstagramHybridListener`, `InstagramRealtimeListener`) for streaming DMs — see [SDK: Real-Time Events](#sdk-real-time-events) below.
• **Multi-account** = multiple Instagram accounts can be stored. Use `auth list` and `auth use` to switch between them.
• **DM-only** = this CLI focuses on Instagram Direct Messages. It does not manage posts, stories, or followers.

Quick Start

# Extract cookies from browser (recommended — zero-config)
agent-instagram auth extract

# Or: Log in with Instagram credentials (fallback)
agent-instagram auth login --username myaccount --password "mypassword"

# List DM conversations
agent-instagram chat list

# Send a message
agent-instagram message send <thread-id> "Hello from agent-instagram"

Authentication Flow

Instagram supports two authentication methods:

1. **Browser cookie extraction** (recommended): Extracts your session cookies from a Chromium browser where you're logged into instagram.com. Zero-config, no password needed. 2. **Username/password login**: Authenticates using Instagram credentials with optional two-factor verification.

Sessions are persisted locally so you don't need to re-authenticate for every command. Browser extraction auto-runs when no session exists.

Browser Cookie Extraction (Recommended)

`agent-instagram auth extract` reads your Instagram session cookies from Chrome, Edge, Arc, Brave, Vivaldi, or Chromium. You must be logged into instagram.com in one of these browsers.

# Extract cookies from browser — zero-config
agent-instagram auth extract

# With debug output
agent-instagram auth extract --debug

# Scan custom Chromium profile/user-data dirs
agent-instagram auth extract --browser-profile ~/browser-data
agent-instagram auth extract --browser-profile "$HOME/work-profile,$HOME/personal-profile"

`--browser-profile` accepts repeatable or comma-separated Chromium profile/user-data directories. Use it for agent-browser profiles, custom Chrome user data dirs, or portable browser profiles.

**How it works**: The CLI reads Instagram cookies (`sessionid`, `csrftoken`, `ds_user_id`) directly from the browser's SQLite cookie database. No browser automation, no password prompts. The session is stored locally in `~/.config/agent-messenger/`.

**When to re-extract**: Browser cookies expire. When your session expires, re-run `agent-instagram auth extract` or let auto-extraction handle it (the CLI attempts extraction automatically when no valid session exists).

**Supported browsers**: Chrome, Chrome Canary, Edge, Arc, Brave, Vivaldi, Chromium

Agent Behavior (MANDATORY)

When a command fails because no account is configured, the agent MUST drive the auth flow itself. Never tell the user to run commands. The agent runs everything.

**Step 1: Check for existing accounts**

agent-instagram auth list

If accounts exist, use `agent-instagram auth use <account-id>` and retry the original command.

**Step 2: Try browser extraction first**

agent-instagram auth extract
# -> {"authenticated":true,"account_id":"12345678","username":"myaccount"}

If extraction succeeds, proceed with the original command.

**Step 3: If extraction fails, ask for credentials**

Ask the user for their Instagram username and password. These are the ONLY things the user needs to provide.

**Step 4: Start login**

agent-instagram auth login --username myaccount --password "mypassword"
# -> {"authenticated":true,"account_id":"myaccount","username":"myaccount"}

**Step 4: Handle 2FA if required**

If login returns `two_factor_required`, ask the user for the verification code:

# -> {"two_factor_required":true,"two_factor_identifier":"abc123","message":"..."}

Then complete verification:

agent-instagram auth verify --username myaccount --code 123456 --identifier abc123
# -> {"authenticated":true,"account_id":"myaccount","username":"myaccount"}

**Step 5: Retry the original command**

After successful auth, immediately execute whatever the user originally asked for.

Common Auth Commands

agent-instagram auth extract                 # Extract cookies from browser (recommended)
agent-instagram auth extract --debug         # Extract with debug output
agent-instagram auth status                  # Check current auth state
agent-instagram auth status --account <id>   # Check specific account
agent-instagram auth list                    # List all stored accounts
agent-instagram auth use <id>                # Switch active account
agent-instagram auth logout                  # Remove curre