Skip to content

Commit b75a8d4

Browse files
pszymkowiakpszymkowiak
authored
Merge pull request #5 from rtk-ai/docs/examples
docs: add 6 usage examples
2 parents d1e5e24 + cdbb35c commit b75a8d4

6 files changed

Lines changed: 516 additions & 0 deletions

File tree

‎examples/01-basic-workflow.sh‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
#!/usr/bin/env bash
2+
# Example: Basic grit workflow — single agent
3+
#
4+
# Demonstrates: init → claim → work → done
5+
6+
set -euo pipefail
7+
8+
PROJECT_DIR=$(mktemp -d)
9+
echo "=== Creating sample project in $PROJECT_DIR ==="
10+
11+
# Create a sample git repo with some code
12+
cd "$PROJECT_DIR"
13+
git init -q
14+
mkdir -p src
15+
16+
cat > src/math.ts << 'EOF'
17+
export function add(a: number, b: number): number {
18+
return a + b;
19+
}
20+
21+
export function subtract(a: number, b: number): number {
22+
return a - b;
23+
}
24+
25+
export function multiply(a: number, b: number): number {
26+
return a * b;
27+
}
28+
29+
export function divide(a: number, b: number): number {
30+
if (b === 0) throw new Error("division by zero");
31+
return a / b;
32+
}
33+
EOF
34+
35+
git add -A && git commit -q -m "initial commit"
36+
37+
# 1. Initialize grit
38+
echo ""
39+
echo "=== Step 1: grit init ==="
40+
grit init
41+
42+
# 2. See what symbols are available
43+
echo ""
44+
echo "=== Step 2: grit symbols ==="
45+
grit symbols
46+
47+
# 3. Agent claims functions to work on
48+
echo ""
49+
echo "=== Step 3: Agent claims 'add' and 'subtract' ==="
50+
grit claim -a agent-1 -i "add input validation" \
51+
"src/math.ts::add" \
52+
"src/math.ts::subtract"
53+
54+
# 4. Check lock status
55+
echo ""
56+
echo "=== Step 4: grit status ==="
57+
grit status
58+
59+
# 5. Agent works in its isolated worktree
60+
echo ""
61+
echo "=== Step 5: Agent edits files in worktree ==="
62+
WORKTREE="$PROJECT_DIR/.grit/worktrees/agent-1"
63+
cat > "$WORKTREE/src/math.ts" << 'EOF'
64+
export function add(a: number, b: number): number {
65+
if (typeof a !== "number" || typeof b !== "number") throw new Error("invalid input");
66+
return a + b;
67+
}
68+
69+
export function subtract(a: number, b: number): number {
70+
if (typeof a !== "number" || typeof b !== "number") throw new Error("invalid input");
71+
return a - b;
72+
}
73+
74+
export function multiply(a: number, b: number): number {
75+
return a * b;
76+
}
77+
78+
export function divide(a: number, b: number): number {
79+
if (b === 0) throw new Error("division by zero");
80+
return a / b;
81+
}
82+
EOF
83+
84+
# 6. Done: auto-commit, rebase, merge, release locks
85+
echo ""
86+
echo "=== Step 6: grit done ==="
87+
grit done -a agent-1
88+
89+
# 7. Verify clean state
90+
echo ""
91+
echo "=== Step 7: Final status (should be empty) ==="
92+
grit status
93+
94+
echo ""
95+
echo "=== Done! Changes merged back to main branch ==="
96+
git log --oneline -5
97+
98+
# Cleanup
99+
rm -rf "$PROJECT_DIR"

‎examples/02-parallel-agents.sh‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
#!/usr/bin/env bash
2+
# Example: Parallel agents — 3 agents working on the same file simultaneously
3+
#
4+
# Demonstrates: multiple claims on different functions in the SAME file,
5+
# parallel worktrees, sequential done (merge serialization)
6+
7+
set -euo pipefail
8+
9+
PROJECT_DIR=$(mktemp -d)
10+
echo "=== Creating sample project in $PROJECT_DIR ==="
11+
12+
cd "$PROJECT_DIR"
13+
git init -q
14+
mkdir -p src
15+
16+
cat > src/auth.ts << 'EOF'
17+
export function validateToken(token: string): boolean {
18+
return token.length > 0;
19+
}
20+
21+
export function refreshToken(token: string): string {
22+
return token + "-refreshed";
23+
}
24+
25+
export function revokeToken(token: string): void {
26+
console.log("revoked:", token);
27+
}
28+
29+
export function generateToken(user: string): string {
30+
return btoa(user + ":" + Date.now());
31+
}
32+
33+
export function parseToken(token: string): { user: string; exp: number } {
34+
const decoded = atob(token);
35+
const [user, exp] = decoded.split(":");
36+
return { user, exp: parseInt(exp) };
37+
}
38+
EOF
39+
40+
git add -A && git commit -q -m "initial commit"
41+
42+
# Initialize
43+
grit init
44+
echo ""
45+
echo "=== Symbols indexed ==="
46+
grit symbols
47+
48+
# 3 agents claim different functions in the SAME file
49+
echo ""
50+
echo "=== Agent 1: claims validateToken + parseToken ==="
51+
grit claim -a agent-1 -i "add JWT validation" \
52+
"src/auth.ts::validateToken" \
53+
"src/auth.ts::parseToken"
54+
55+
echo ""
56+
echo "=== Agent 2: claims refreshToken ==="
57+
grit claim -a agent-2 -i "add expiry check" \
58+
"src/auth.ts::refreshToken"
59+
60+
echo ""
61+
echo "=== Agent 3: claims generateToken ==="
62+
grit claim -a agent-3 -i "use crypto.randomUUID" \
63+
"src/auth.ts::generateToken"
64+
65+
echo ""
66+
echo "=== Status: 3 agents, same file, no conflicts ==="
67+
grit status
68+
69+
# Agent 2 tries to claim a symbol already held by Agent 1
70+
echo ""
71+
echo "=== Agent 2 tries to claim parseToken (held by Agent 1) ==="
72+
grit claim -a agent-2 -i "also want parseToken" \
73+
"src/auth.ts::parseToken" 2>&1 || echo " → Blocked as expected!"
74+
75+
# Each agent edits in their own worktree
76+
echo ""
77+
echo "=== Agents work in parallel worktrees ==="
78+
ls -la .grit/worktrees/
79+
80+
# Agent 1 finishes
81+
echo ""
82+
echo "=== Agent 1: done ==="
83+
grit done -a agent-1
84+
85+
# Agent 2 finishes
86+
echo ""
87+
echo "=== Agent 2: done ==="
88+
grit done -a agent-2
89+
90+
# Agent 3 finishes
91+
echo ""
92+
echo "=== Agent 3: done ==="
93+
grit done -a agent-3
94+
95+
echo ""
96+
echo "=== Final status: all locks released ==="
97+
grit status
98+
99+
echo ""
100+
echo "=== Git log: each agent's merge is a separate commit ==="
101+
git log --oneline -10
102+
103+
rm -rf "$PROJECT_DIR"

‎examples/03-session-pr.sh‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
#!/usr/bin/env bash
2+
# Example: Session workflow — feature branch + GitHub PR
3+
#
4+
# Demonstrates: session start → agents work → session pr → session end
5+
# NOTE: This example requires a GitHub remote to create PRs.
6+
# Run it in a real repo with `gh` CLI configured.
7+
8+
set -euo pipefail
9+
10+
echo "=== Session Workflow ==="
11+
echo "This example shows the full session lifecycle."
12+
echo "Run it in a real git repo with a GitHub remote."
13+
echo ""
14+
15+
# 1. Start a session (creates branch grit/<name>)
16+
echo "$ grit session start auth-refactor"
17+
echo " → Creates branch grit/auth-refactor"
18+
echo " → Records base branch for PR"
19+
echo ""
20+
21+
# 2. Agents claim and work
22+
echo "$ grit claim -a agent-1 -i 'add JWT' src/auth.ts::validateToken"
23+
echo "$ grit claim -a agent-2 -i 'add OAuth' src/auth.ts::oauthLogin"
24+
echo " → Each agent gets an isolated worktree"
25+
echo ""
26+
27+
# 3. Check session status
28+
echo "$ grit session status"
29+
echo " → Shows: branch, base, active agents, locked symbols"
30+
echo ""
31+
32+
# 4. Agents finish
33+
echo "$ grit done -a agent-1"
34+
echo "$ grit done -a agent-2"
35+
echo " → Each merge is serialized (no conflicts)"
36+
echo ""
37+
38+
# 5. Create PR
39+
echo "$ grit session pr --title 'Auth refactor: JWT + OAuth'"
40+
echo " → Pushes branch to origin"
41+
echo " → Creates GitHub PR with session summary"
42+
echo ""
43+
44+
# 6. End session
45+
echo "$ grit session end"
46+
echo " → Cleans up expired locks"
47+
echo " → Switches back to base branch"
48+
echo ""
49+
50+
echo "=== Full command sequence ==="
51+
cat << 'CMD'
52+
grit init
53+
grit session start auth-refactor
54+
55+
grit claim -a agent-1 -i "add JWT validation" src/auth.ts::validateToken
56+
grit claim -a agent-2 -i "add OAuth flow" src/auth.ts::oauthLogin
57+
58+
# ... agents edit in .grit/worktrees/agent-{1,2}/ ...
59+
60+
grit done -a agent-1
61+
grit done -a agent-2
62+
63+
grit session pr --title "Auth refactor: JWT + OAuth"
64+
grit session end
65+
CMD

‎examples/04-s3-backend.sh‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
#!/usr/bin/env bash
2+
# Example: S3-compatible backend — distributed lock coordination
3+
#
4+
# Demonstrates: configuring grit to use S3/R2/MinIO for locks,
5+
# enabling multi-machine agent coordination.
6+
7+
set -euo pipefail
8+
9+
echo "=== S3 Backend Configuration ==="
10+
echo ""
11+
echo "By default, grit uses SQLite (local). For distributed teams"
12+
echo "or cloud-based agents, switch to an S3-compatible backend."
13+
echo ""
14+
15+
echo "--- AWS S3 ---"
16+
cat << 'CMD'
17+
export AWS_ACCESS_KEY_ID=...
18+
export AWS_SECRET_ACCESS_KEY=...
19+
20+
grit init
21+
grit config set-s3 --bucket my-grit-locks --region us-east-1
22+
grit config show
23+
CMD
24+
25+
echo ""
26+
echo "--- Cloudflare R2 ---"
27+
cat << 'CMD'
28+
export AWS_ACCESS_KEY_ID=... # R2 API token
29+
export AWS_SECRET_ACCESS_KEY=...
30+
31+
grit init
32+
grit config set-s3 \
33+
--bucket grit-locks \
34+
--endpoint https://<account-id>.r2.cloudflarestorage.com \
35+
--region auto
36+
CMD
37+
38+
echo ""
39+
echo "--- MinIO (self-hosted) ---"
40+
cat << 'CMD'
41+
export AWS_ACCESS_KEY_ID=minioadmin
42+
export AWS_SECRET_ACCESS_KEY=minioadmin
43+
44+
grit init
45+
grit config set-s3 \
46+
--bucket grit-locks \
47+
--endpoint http://localhost:9000 \
48+
--region us-east-1
49+
CMD
50+
51+
echo ""
52+
echo "--- Google Cloud Storage (S3-compatible) ---"
53+
cat << 'CMD'
54+
export AWS_ACCESS_KEY_ID=... # HMAC key
55+
export AWS_SECRET_ACCESS_KEY=...
56+
57+
grit init
58+
grit config set-s3 \
59+
--bucket grit-locks \
60+
--endpoint https://storage.googleapis.com \
61+
--region auto
62+
CMD
63+
64+
echo ""
65+
echo "--- Switch back to local ---"
66+
cat << 'CMD'
67+
grit config set-local
68+
grit config show
69+
CMD
70+
71+
echo ""
72+
echo "=== How S3 locking works ==="
73+
echo "Each lock is an S3 object:"
74+
echo " Key: .grit/locks/{url_encoded_symbol_id}"
75+
echo " Body: JSON LockEntry (agent, intent, TTL, timestamp)"
76+
echo ""
77+
echo "Atomic acquisition via conditional PUT (If-None-Match: *)"
78+
echo " → Only one agent can create the lock object"
79+
echo " → Race conditions handled with retry logic"

0 commit comments

Comments
 (0)