# xrithm

An AI-powered tool to help you write better X content without sounding like a robot.

`xrithm` is an open source tool for developers, founders, and builders who want to turn real ideas into stronger X posts without sounding like generic AI content. It currently uses Groq for fast, inexpensive OpenAI-compatible inference. For production, the same client shape can switch to xAI/Grok to support the "same AI family as X's quality screen" narrative.

## Features

- Analyze viral post patterns by niche
- Generate 10 hook variations from proven patterns
- Generate a single post and full thread from your ideas
- Score drafts using algorithm-aligned criteria
- Find trend angles for tech, startup, dev, AI, and Africa-focused niches
- Track your own X patterns from historical posts
- Train a local voice profile from your own writing samples

## Quick Start

```bash
git clone <repo-url>
cd xrithm
cp .env.example .env
pnpm install
pnpm build
npm link
```

Add your API keys to `.env`, then try:

```bash
xrithm hooks --topic "I just shipped my first open source tool"
```

## CLI Reference

| Command | Purpose |
| --- | --- |
| `xrithm hooks --topic "<topic>"` | Generate 10 hooks |
| `xrithm generate --topic "<topic>" --bullets "a,b,c"` | Generate a post and thread |
| `xrithm score --draft draft.txt` | Score a post |
| `xrithm analyze --niche "<niche>"` | Analyze viral posts in a niche |
| `xrithm trends --niche "<niche>"` | Find trend angles |
| `xrithm tracker --username @handle` | Analyze a user's posts |
| `xrithm voice train --samples samples.txt` | Train local voice profile |
| `xrithm voice show` | Show current voice profile |

## Web Dashboard

xrithm includes a local dashboard for a visual workflow.

```bash
xrithm gui
```

It opens at `http://localhost:3420`. No account, no cloud, everything runs locally.

## API Keys

Groq is required for generation and scoring. X API keys are required for analyzer and tracker commands. See [docs/api-keys-setup.md](docs/api-keys-setup.md).

xrithm uses Groq's OpenAI-compatible API:

```ts
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.GROQ_API_KEY,
  baseURL: 'https://api.groq.com/openai/v1',
})
```

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT