Save now. Read never. Find always.

For people who bookmark everything and read nothing. A Twitter/X bookmark manager that actually helps you find that tweet you saved 6 months ago.

Save tweets instantly by adding adh before any x.com URL:

x.com/user/status/123456789
  ↓
adhx.com/user/status/123456789

The tweet is saved to your collection and opens in the lightbox. It's that easy. Your future self will thank you. Probably.

• Node.js 20+
• pnpm
• Twitter/X Developer Account (for OAuth credentials)
• A concerning number of unread bookmarks

# Clone the repo
git clone https://github.com/itsmemeworks/adhx
cd adhx

# Install dependencies
pnpm install

# Copy environment template
cp .env.example .env

# Start dev server
pnpm dev

Open http://localhost:3000 and connect your Twitter/X account.

Create a .env file:

# Twitter OAuth 2.0 credentials (from developer.twitter.com)
TWITTER_CLIENT_ID=your_client_id
TWITTER_CLIENT_SECRET=your_client_secret

# App URL (for OAuth callback)
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Session security (generate a random string)
SESSION_SECRET=your-secret-key-here

1. Go to developer.twitter.com
2. Create a new project and app
3. Enable OAuth 2.0 with PKCE
4. Set callback URL to http://localhost:3000/api/auth/twitter/callback
5. Copy the Client ID and Client Secret
6. Try not to get distracted by your timeline

pnpm dev          # Start dev server
pnpm build        # Production build
pnpm test         # Run tests
pnpm test:watch   # Run tests in watch mode
pnpm typecheck    # TypeScript check
pnpm db:migrate   # Run database migrations

ADHX is configured for deployment on Fly.io with persistent SQLite storage.

# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Login to Fly
fly auth login

# Create the app (first time only)
fly apps create your-app-name

# Create persistent volume for SQLite database
fly volumes create adhx_data --region lhr --size 1

# Set secrets (replace with your domain)
fly secrets set TWITTER_CLIENT_ID=your_client_id
fly secrets set TWITTER_CLIENT_SECRET=your_client_secret
fly secrets set SESSION_SECRET=$(openssl rand -base64 32)
fly secrets set NEXT_PUBLIC_APP_URL=https://your-app-name.fly.dev

# Deploy
fly deploy

1. Update your Twitter app's callback URL to match your domain:
   • Local: http://localhost:3000/api/auth/twitter/callback
   • Fly.io: https://your-app-name.fly.dev/api/auth/twitter/callback
2. Visit your app URL and connect your Twitter account

Releases are automated via Release Please:

1. Merge PRs with conventional commits to main
2. Release Please creates/updates a release PR with changelog
3. Merge the release PR → automatically deploys to Fly.io

Manual deploy: gh workflow run deploy.yml

ADHX ships as an Agent Skill — an open, portable format for giving AI agents new capabilities. Paste any X/Twitter link into your agent of choice and it can fetch the post as clean JSON, no browser or scraping needed.

The adhx skill follows the agentskills.io specification, so it works across any skills-compatible agent, including: Claude Code, Claude, Cursor, Gemini CLI, OpenCode, OpenAI Codex, GitHub Copilot, Goose, Kiro, VS Code (Copilot), Letta, Factory, Roo Code, Amp, and more.

📂 Skill source: skills/adhx/SKILL.md

The skill is a single folder you drop into your agent's skills directory. Location varies by agent:

Check your agent's docs if your client isn't listed — the install path may differ, but the skill file itself is identical everywhere.

One-line install (replace <SKILLS_DIR> with the path from the table above):

mkdir -p <SKILLS_DIR>/adhx && \
  curl -sL https://raw.githubusercontent.com/itsmemeworks/adhx/main/skills/adhx/SKILL.md \
  -o <SKILLS_DIR>/adhx/SKILL.md

Claude Code marketplace (shortcut for Claude Code users):

/plugin marketplace add itsmemeworks/adhx
/plugin install adhx

Re-run the same install command — it overwrites the existing SKILL.md with the latest version. For the Claude Code marketplace install, use /plugin update adhx.

# Example for Claude Code
curl -sL https://raw.githubusercontent.com/itsmemeworks/adhx/main/skills/adhx/SKILL.md \
  -o ~/.claude/skills/adhx/SKILL.md

Once installed, paste any X link into your agent and ask it to read/summarize/analyze:

> Read this and give me the key takeaways https://x.com/dgt10011/status/2020167690560647464

The agent will automatically call the ADHX public API and return structured JSON with the full post content, author info, and engagement metrics — including long-form X Articles.

GET https://adhx.com/api/share/tweet/{username}/{statusId}

No auth required. Works with x.com, twitter.com, and adhx.com URLs.

We welcome contributions! Whether you're fixing bugs, adding features, or just improving docs.

Quick start:

1. Fork the repo
2. Create a branch (git checkout -b feat/amazing-feature)
3. Make your changes
4. Commit with conventional commits (git commit -m 'feat: add amazing feature')
5. Push and open a PR

See CONTRIBUTING.md for detailed guidelines.

We use conventional commits for automatic versioning:

feat: add new feature      # → Minor version bump
fix: resolve bug           # → Patch version bump
feat!: breaking change     # → Major version bump

src/
├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   │   ├── auth/          # Twitter OAuth flow
│   │   ├── bookmarks/     # Bookmark CRUD
│   │   ├── feed/          # Main feed endpoint
│   │   └── sync/          # Sync with Twitter
│   ├── settings/          # Settings page
│   └── page.tsx           # Main feed page
├── components/
│   ├── feed/              # Feed components
│   └── ...
└── lib/
    ├── db/                # Database schema
    ├── auth/              # OAuth utilities
    └── media/             # FxTwitter integration

Found a security issue? Please report it privately. See SECURITY.md for details.

MIT © ADHX

Built for people who save tweets about productivity while procrastinating.

adhx.com