Examples & Tutorials Interactive
Learn Automergent through real-world examples. Each tutorial shows the full interaction — from your input to the agent's reasoning and final output.
⭐ Quick Examples
These examples show common one-shot interactions — type a message, the agent figures out the rest.
main.go is the entry point for the application. It:
- Initializes a new CLI application using
cobra - Registers subcommands (
serve,config,migrate) - Loads configuration from
~/.automergent/config.yaml - Starts an HTTP server on the configured port
The init() function sets up logging and telemetry before the main command runs.
Summary: 7 items found. 4 TODOs, 1 FIXME, 1 HACK. The FIXME in db/pool.go:12 looks most urgent.
Diagnosis: Both failures trace to the same root cause — ValidateToken() now checks exp claims but the test tokens use a stale expiry. Fixing the test fixture timestamps.
All 14 tests pass now. The issue was that the test fixture's JWT tokens expired in December 2025 — I updated them to use relative time offsets.
Which function? I'll look at the current file context first.
Here's my plan for refactoring parseRequest() (lines 45-92):
- Extract validation logic into a separate
validatePayload()function - Replace nested if-else with early returns
- Add named return values for clarity
Refactored. The function went from 47 lines with 4 nesting levels to 28 lines with max 2. All tests pass.
Project: go-app — Go 1.22, module-based architecture
├── cmd/ Entry points (one per binary) │ ├── serve/ │ └── migrate/ ├── internal/ Private packages │ ├── auth/ JWT + middleware │ ├── db/ PostgreSQL + migrations │ └── handler/ HTTP handlers ├── pkg/ Public API packages ├── web/ Static assets + templates ├── migrations/ SQL migration files └── deploy/ Docker + Kubernetes configs
This is a standard Go project layout following the golang-standards/project-layout conventions. Key patterns:
- Clean Architecture:
internal/packages have no circular deps - Dependency injection: Constructor funcs in
cmd/serve/main.gowire everything - Interface-driven:
db.Repositoryinterface lets handlers be tested with mocks - Graceful shutdown: Signal handling + context propagation
📩 Workflow: Code Review
A structured workflow for reviewing changes before merge.
Reviewing branch: feature/user-settings (14 commits, +842 / -127)
✓ Correctness
All logic paths look sound. The settings update properly validates input before writing to the database.
⚠ Suggestions
settings.go:34 — The UpdateUserSettings function doesn't check if the user exists before updating. Add a GetUser call first to avoid silent no-ops.
handler.go:67 — Missing error context. fmt.Errorf("update failed") should wrap the underlying error with %w.
␒ Notes
- Migration adds an index on
user_settings.user_id— good, matches the query pattern - New tests are thorough — 94% coverage on changed files
Verdict: Minor issues only. Approved with the two fixes above.
🐛 Workflow: Bug Investigation
Methodically tracing a bug from symptom to root cause.
Investigation log:
1. Last 5 deploys touched auth/, db/, and config/
2. git diff HEAD~5..HEAD auth/ shows the middleware was changed to require exp claim validation
3. But the token signing code in auth/token.go:45 still uses time.Now().Add(24 * time.Hour) — this looks correct
4. Checking the config…
Found it. The config change in deploy/config.yaml switched token_issuer from "app" to "App" (capitalized). The middleware validates iss claim case-sensitively, so all existing tokens are rejected.
Fix: Revert the issuer value to lowercase, or make the comparison case-insensitive.
✨ Workflow: Feature Implementation
Plan-driven feature development with approval gates.
Generating plan artifact…
## Rate Limiter Middleware ### Goal Add configurable rate limiting to protect API endpoints. ### Steps 1. Create internal/ratelimit/limiter.go - Token bucket algorithm (using golang.org/x/time/rate) - Interfaces: PerUserLimiter, PerIPLimiter - In-memory store with cleanup goroutine 2. Create internal/ratelimit/middleware.go - Extract user ID from JWT or IP from RemoteAddr - Check rate, return 429 with Retry-After header 3. Add config fields to config.yaml - ratelimit.enabled: true - ratelimit.per_user: "100/m" - ratelimit.per_ip: "30/m" 4. Wire into cmd/serve/main.go 5. Add tests ### Risks - In-memory store won't survive restarts (acceptable for MVP) - No distributed rate limiting (add Redis later if needed) ### Files to create/modify - Create: internal/ratelimit/limiter.go - Create: internal/ratelimit/middleware.go - Create: internal/ratelimit/limiter_test.go - Modify: cmd/serve/main.go - Modify: config/config.go
All 11 tests pass. The rate limiter is implemented with:
- Per-user: 100 req/min (configurable)
- Per-IP: 30 req/min (configurable)
- Returns
429 Too Many RequestswithRetry-Afterheader
🔧 Workflow: Refactoring
Current state: db.Store is a concrete struct used directly in 6 files. I'll extract an interface incrementally.
Repository interface in db/interface.goStore implement the interface (it already does)RepositoryRefactoring complete. Every function that used *db.Store now accepts db.Repository. You can now create a MockStore for testing or swap to a different backend.
🤖 Sub-agent Examples
Automergent can spawn sub-agents to work in parallel on different tasks.
| Agent | Scope | Status | Result |
|---|---|---|---|
agent-1 |
src/ |
✓ done | 42 functions across 8 files. Core modules: api, auth, cache, db |
agent-2 |
tests/ |
✓ done | 89 test functions. Coverage: 78%. Missing tests for cache layer |
agent-3 |
docs/ |
✓ done | 3 markdown docs. API docs outdated (last updated 3 months ago) |
Summary: The codebase is well-structured. Two action items: write cache layer tests and update API docs.
review agent targeting internal/auth/Security Review — internal/auth/
| Severity | Finding | File |
|---|---|---|
| HIGH | JWT secret read from env without length validation — weak secrets accepted | token.go:18 |
| MEDIUM | Password comparison not constant-time (using == instead of subtle.ConstantTimeCompare) |
password.go:34 |
| MEDIUM | Session token not invalidated on password change | handler.go:89 |
| LOW | Missing rate limit on /login endpoint |
handler.go:22 |
The sub-agent recommends fixing the HIGH and MEDIUM issues before the next release.
http://localhost:3000Dev server is running in the background. What do you need help with on the UI?
Fixed. The hamburger button was missing an onClick handler. Added the toggle state and a click listener. Your browser should have hot-reloaded.