Install to Claude Code
npx -y skills add https://github.com/aradotso/trending-skills --skill karpathytalk-communityDescription
karpathytalk community
SKILL.md
---
name: karpathytalk-community
description: Run and interact with KarpathyTalk, an open markdown-based developer social network with GitHub auth, SQLite, and an LLM-friendly JSON/markdown API.
triggers:
- set up KarpathyTalk locally
- run a developer social network in Go
- deploy KarpathyTalk to a server
- use the KarpathyTalk API
- create posts on KarpathyTalk
- build an agent that reads KarpathyTalk
- configure GitHub OAuth for KarpathyTalk
- self-host a markdown social platform
---
# KarpathyTalk Community Skill
> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.
KarpathyTalk is a Go-based developer social network (Twitter × GitHub Gists) where posts are plain markdown, the social layer supports likes/reposts/follows/replies, and all data is openly accessible via JSON and markdown APIs — designed for both humans and LLM agents.
---
## What It Does
- GitHub OAuth sign-in (no new credentials)
- Posts are GFM markdown with syntax-highlighted code blocks and image uploads
- Social features: likes, reposts, quote posts, replies, follows
- REST API returns JSON (for agents/code) or markdown (for humans)
- Single Go binary + SQLite + `uploads/` directory — trivial to self-host
- Built with: Go, SQLite, htmx, goldmark
---
## Installation & Local Setup
### 1. Create a GitHub OAuth App
Go to **GitHub → Settings → Developer settings → OAuth Apps → New OAuth App**:
| Field | Value |
|---|---|
| Application name | KarpathyTalk |
| Homepage URL | `http://localhost:8080` |
| Authorization callback URL | `http://localhost:8080/auth/callback` |
Save the **Client ID** and **Client Secret**.
### 2. Clone & Build
```bash
git clone https://github.com/karpathy/KarpathyTalk.git
cd KarpathyTalk
go build -o karpathytalk ./cmd/karpathytalk
```
### 3. Configure Environment
```bash
export GITHUB_CLIENT_ID=$GITHUB_CLIENT_ID
export GITHUB_CLIENT_SECRET=$GITHUB_CLIENT_SECRET
export BASE_URL=http://localhost:8080 # optional, defaults to this
```
### 4. Run
```bash
./karpathytalk
# or with options:
./karpathytalk -addr :9090 -db ./data/karpathytalk.db
```
Visit `http://localhost:8080`.
---
## CLI Flags
```
-addr string HTTP listen address (default ":8080")
-db string SQLite database path (default "karpathytalk.db")
```
---
## Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| `GITHUB_CLIENT_ID` | ✅ | — | GitHub OAuth client ID |
| `GITHUB_CLIENT_SECRET` | ✅ | — | GitHub OAuth client secret |
| `BASE_URL` | ❌ | `http://localhost:8080` | Public URL of the deployed app |
---
## Deployment (Production)
### Build & Copy
```bash
# Build binary
go build -o karpathytalk ./cmd/karpathytalk
# Copy to server (adjust user/host)
scp karpathytalk schema.sql user@yourserver:~/karpathytalk/
scp -r templates static user@yourserver:~/karpathytalk/
```
### Run on Server
```bash
ssh user@yourserver
cd ~/karpathytalk
export GITHUB_CLIENT_ID=$GITHUB_CLIENT_ID
export GITHUB_CLIENT_SECRET=$GITHUB_CLIENT_SECRET
export BASE_URL=https://yourdomain.com
./karpathytalk -addr :8080
```
### Caddy TLS (recommended)
```caddyfile
yourdomain.com {
reverse_proxy localhost:8080
}
```
### nginx TLS
```nginx
server {
listen 443 ssl;
server_name yourdomain.com;
ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
location / {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### systemd Service
```ini
[Unit]
Description=KarpathyTalk
After=network.target
[Service]
WorkingDirectory=/home/deploy/karpathytalk
ExecStart=/home/deploy/karpathytalk/karpathytalk -addr :8080
Restart=always
Environment=GITHUB_CLIENT_ID=$GITHUB_CLIENT_ID
Environment=GITHUB_CLIENT_SECRET=$GITHUB_CLIENT_SECRET
Environment=BASE_URL=https://yourdomain.com
[Install]
WantedBy=multi-user.target
```
---
## API Usage
All data is open — no auth required for reads. The API returns JSON for programmatic access and markdown for human/agent reading.
### Fetch Posts as JSON
```bash
# Timeline / recent posts
curl https://karpathytalk.com/api/posts
# Single post
curl https://karpathytalk.com/api/posts/{postID}
# User's posts
curl https://karpathytalk.com/api/users/{username}/posts
```
### Fetch Posts as Markdown
```bash
# Human/agent-readable markdown
curl https://karpathytalk.com/api/posts/{postID}.md
```
### Go Agent Example — Read Timeline
```go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
)
type Post struct {
ID int64 `json:"id"`
Username string `json:"username"`
Content string `json:"content"`
Likes int `json:"likes"`
Reposts int `json:"reposts"`
CreatedAt string `json:"created_at"`
}
func fetchTimeline(baseURL string) ([]Post, error) {
resp, err := http.Get(baseURL + "/api/posts")
if err != nil {
return nil, err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return nil, err
}
var posts []Post
if err := json.Unmarshal(body, &posts); err != nil {
return nil, err
}
return posts, nil
}
func main() {
posts, err := fetchTimeline("https://karpathytalk.com")
if err != nil {
panic(err)
}
for _, p := range posts {
fmt.Printf("[%s] %s (👍 %d)\n", p.Username, p.Content[:min(80, len(p.Content))], p.Likes)
}
}
func min(a, b int) int {
if a < b {
return a
}
return b
}
```
### Go Agent Example — Fetch User Posts as Markdown
```go
package main
import (
"fmt"
"io"
"net/http"
)
func fetchUserPostsMarkdown(baseURL, username string) (string, error) {
url := fmt.Sprintf("%s/api/users/%s/posts.md", baseURL, username)
resp, err := http.Get(url)
if err != nil {
return "", err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
return string(body), err
}
func main() {
md, err := fetchUserPostsMarkdown("https://karpathytalk.com", "karpathy")
if err != nil {
panic(err)
}
fmt.Println(md)
}
```
---
## Content Limits
| Content Type | Max Length | Rate Limit |
|---|---|---|
| Posts | 10,000 characters | 30 per hour |
| Replies | 5,000 characters | 60 per hour |
| Images | 5 MB | PNG/JPEG/GIF/WebP only |
---
## Database — Direct SQLite Access
The SQLite database is a single file. You can query it directly for analytics, backups, or migrations:
```bash
# Open database
sqlite3 karpathytalk.db
# List tables
.tables
# Recent posts
SELECT username, substr(content, 1, 80), created_at
FROM posts
ORDER BY created_at DESC
LIMIT 20;
# Most liked posts
SELECT username, likes, substr(content, 1, 60)
FROM posts
ORDER BY likes DESC
LIMIT 10;
# User follower counts
SELECT username, COUNT(*) as followers
FROM follows
GROUP BY username
ORDER BY followers DESC;
```
### Backup
```bash
# Simple file copy (safe while running with WAL mode)
cp karpathytalk.db karpathytalk.db.backup
# Or use sqlite3 online backup
sqlite3 karpathytalk.db ".backup karpathytalk_backup.db"
```
---
## Project Structure
```
KarpathyTalk/
├── cmd/
│ └── karpathytalk/ # main entrypoint
├── templates/ # HTML templates (htmx-powered)
├── static/ # CSS, JS assets
├── uploads/ # User image uploads
├── schema.sql # SQLite schema
└── karpathytalk.db # Database (created at runtime)
```
---
## Common Patterns
### Pattern: Agent That Monitors New Posts
```go
package main
import (
"encoding/json"
"fmt"
"net/http"
"time"
)
type Post struct {
ID int64 `json:"id"`
Username string `json:"username"`
Content string `json:"content"`
CreatedAt string `json:"created_at"`
}
func pollNewPosts(baseURL string, sinceID int64) ([]Post, error) {
url := fmt.Sprintf("%s/api/posts?since_id=%d", baseURL, sinceID)
resp, err := http.Get(url)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var posts []Post
json.NewDecoder(resp.Body).Decode(&posts)
return posts, nil
}
func main() {
var lastSeenID int64 = 0
for {
posts, err := pollNewPosts("https://karpathytalk.com", lastSeenID)
if err != nil {
fmt.Println("Error:", err)
} else {
for _, p := range posts {
fmt.Printf("New post by @%s: %s\n", p.Username, p.Content[:min(60, len(p.Content))])
if p.ID > lastSeenID {
lastSeenID = p.ID
}
}
}
time.Sleep(30 * time.Second)
}
}
func min(a, b int) int {
if a < b { return a }
return b
}
```
### Pattern: Embedding KarpathyTalk Content in an LLM Prompt
```go
package main
import (
"fmt"
"io"
"net/http"
)
// Fetch markdown content to inject into an LLM system prompt or context window
func getContextForLLM(baseURL, username string) (string, error) {
url := fmt.Sprintf("%s/api/users/%s/posts.md", baseURL, username)
resp, err := http.Get(url)
if err != nil {
return "", err
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
return string(body), err
}
func main() {
context, _ := getContextForLLM("https://karpathytalk.com", "karpathy")
systemPrompt := fmt.Sprintf(`You are a helpful assistant. Here are recent posts from the community:
%s
Answer questions about these posts.`, context)
fmt.Println(systemPrompt)
}
```
---
## Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| `GITHUB_CLIENT_ID not set` | Missing env var | Export `GITHUB_CLIENT_ID` before running |
| OAuth callback fails | Callback URL mismatch | Ensure GitHub OAuth App callback URL exactly matches `BASE_URL/auth/callback` |
| Binary not found after build | Wrong output path | Run `go build -o karpathytalk ./cmd/karpathytalk` from repo root |
| `templates: no such file` | Missing templates dir | Run the binary from the repo root, or copy `templates/` and `static/` next to the binary |
| Database locked | Concurrent writers | SQLite WAL mode is set by default; avoid multiple binary instances against same `.db` |
| Images not serving | Missing `uploads/` dir | The directory is created automatically on first upload; check write permissions |
| Port already in use | Another process on 8080 | Use `-addr :9090` to change the port |
### Check the App is Running
```bash
curl -I http://localhost:8080/
# Expect: HTTP/1.1 200 OK
```
### Rebuild After Code Changes
```bash
go build -o karpathytalk ./cmd/karpathytalk && ./karpathytalk
```
### Run Tests
```bash
go test ./...
```