Context-aware handoffs for Claude Code that prevent knowledge loss across sessions.
Landing Page · Thinking Protocol · Why JKS?
AI coding agents lose context during long sessions. When context compresses, nuanced details vanish — architecture decisions, data structures, edge cases. The agent keeps working but makes subtly wrong decisions.
Context compression is inevitable. Knowledge loss is not.
# Plugin install (recommended)
/plugin marketplace add cyber-qais/justkeepswimming
/plugin install justkeepswimming
# Or manual install
mkdir -p ~/.claude/commands/justkeepswimming
cp commands/justkeepswimming/*.md ~/.claude/commands/justkeepswimming/Then:
/justkeepswimming:go my-feature
Session 1 Session 2 Session 3
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ Execute │ │ Read handoff │ │ Read handoff │
│ Phase 1 ✓ │ │ (full context) │ │ (full context) │
│ Phase 2 ✓ │ │ │ │ │
│ │ │ Execute │ │ Execute │
│ Context heavy │ │ Phase 3 ✓ │ │ Phase 5 ✓ │
│ ┌─────────────┐ │ │ Phase 4 ✓ │ │ Phase 6 ✓ │
│ │ HANDOFF │─┼────────>│ │ │ │
│ │ ·progress │ │ │ Context heavy │ │ ┌─────────────┐ │
│ │ ·learnings │ │ │ ┌─────────────┐ │ │ │ COMPLETE │ │
│ │ ·context │ │ │ │ HANDOFF │─┼────────>│ │ SUMMARY.md │ │
│ └─────────────┘ │ │ │ ·cumulative│ │ │ └─────────────┘ │
└─────────────────┘ │ └─────────────┘ │ └─────────────────┘
└─────────────────┘
Each handoff captures cumulative context — condensed knowledge from ALL prior sessions merged into one section. Session 3's agent reads ONE document and knows everything sessions 1 and 2 discovered.
| What it does | How |
|---|---|
| Creates plans | From scratch, from conversation context (--from-context), or imported |
| Executes continuously | Phase by phase, autonomous or interactive |
| Hands off automatically | Detects context health, writes handoff before degradation |
| Resumes seamlessly | Reads all prior handoffs, restores full context |
| Maintains completed work | Structured debugging with maintenance logs |
| Phase | What happens |
|---|---|
| Discover | Reads CLAUDE.md, detects tech stack, deployment targets |
| Review | Scans last 12h of commits, checks end-to-end wiring |
| Code Review | Finds bugs, fixes HIGH-confidence issues |
| Syntax Check | Validates JS/TS, Python, Dart, Rust, Go |
| Test | Runs project test suite |
| Build & Deploy | Builds, deploys, restarts services, notifies users |
| Summary | Writes detailed report, self-reviews for gaps |
| Commit & Push | Stages, commits, pushes to git |
Fully autonomous. No prompts. Adapts to any project.
/justkeepswimming:go [plan-name] [flags]
| Flag | Effect |
|---|---|
| (none) | Autonomous mode. Execute continuously, handoff automatically. |
--interactive |
Pause after each phase for review. |
--from-context |
Build plan from current conversation. |
--now |
--from-context + skip confirmations. Just go. |
Combine them: --now --interactive builds plan instantly, pauses between phases.
# Handoff — API Migration — Session 002
**Progress**: 4 of 6 phases complete (~67%)
**Handoff trigger**: 2 phases completed + context compression detected
## Completed This Session
- [x] Phase 3: Auth middleware — `middleware/auth.js:42-89`
- [x] Phase 4: Rate limiting — `services/rateLimiter.js:1-156`
## Key Learnings
- Redis cache uses `user:{id}:session` key scheme (TTL 30min)
- Auth tokens checked via middleware, NOT route-level
## Cumulative Context (All Sessions)
- API uses Express 4.x with router-level middleware
- Database: PostgreSQL via Knex, migrations in `db/migrations/`
- Session 1 discovered: connection pooling maxes at 20
- Session 2 discovered: rate limiter must exempt /health endpointEvery learning, every decision, every file reference — preserved across sessions.
Most agents pattern-match to common fixes and guess. JKS agents verify conditions for success.
|
Without Thinking Protocol 3 attempts, hoping one sticks. |
With Thinking Protocol 1 targeted fix at the root cause. |
Six principles injected into every session:
| # | Principle | One-liner |
|---|---|---|
| 1 | Diagnose before you prescribe | Gather facts before forming hypotheses |
| 2 | Trace the full chain | List every condition, verify each one |
| 3 | Check what's actually there | Read output with an open mind |
| 4 | Know the silent failures | Systems fail without useful errors |
| 5 | Minimum effective intervention | Fix root cause only |
| 6 | Resist "the usual fix" | If it's been tried, check a different layer |
Customize by editing THINKING.md. Your team's hard-won debugging lessons get injected into every future session.
The skill detects your context window and enforces hard limits:
| Context Window | Max Phases | Why |
|---|---|---|
| Standard (~200k) | 2 | Each phase consumes significant context |
| Extended (1M) | 5 | More room, but still finite |
When budget is hit, the agent hands off. No negotiation, no "just one more thing."
Plan complete? JKS stays useful. When bugs surface or changes are needed:
/justkeepswimming:go my-feature
> "That plan is complete. Maintenance mode?"
- Restores context from SUMMARY.md
- Applies Thinking Protocol to every investigation
- Creates maintenance logs with investigation steps, changes, and verification
- Escalates to a new plan if scope exceeds a targeted fix
| Just Keep Swimming | Heavy workflow systems | |
|---|---|---|
| Files | 2 commands + 1 methodology doc | 30+ files, state tracking |
| State | Handoff documents only | STATE.md, ROADMAP.md, CONTEXT.md, ... |
| Concepts | Plan, Execute, Handoff | Projects, Milestones, Phases, Waves, Audits |
| Setup | Copy 2 files or install plugin | Plugin + configuration + learning curve |
| Best for | Getting things done | Managing complex parallel workstreams |
your-project/
└── docs/justkeepswimming/
├── api-migration/
│ ├── PLAN.md # The plan
│ ├── 2026-03-12-handoff-001.md # Session 1
│ ├── 2026-03-13-handoff-002.md # Session 2
│ ├── 2026-03-14-handoff-003.md # Final (COMPLETE)
│ ├── 2026-03-15-maintenance-001.md # Post-delivery fix
│ └── SUMMARY.md # Architecture overview
└── night-build/
└── 2026-03-14-night-build.md # Build report
Plain markdown files. Commit them, branch them, git blame them.
- Claude Code (any recent version)
- superpowers plugin (optional) — for auto-generated plans via
superpowers:writing-plans
No superpowers? Import your own plans or use --from-context.
What if I forget to say "handoff"?
Autonomous mode monitors context health and creates handoffs automatically. You don't need to do anything.Can I use this without the superpowers plugin?
Yes. Import your own plan or use--from-context to synthesize from conversation.
What happens when the plan is complete?
The agent creates a final COMPLETE handoff, generates SUMMARY.md with architecture overview and next steps, then offers to turn recommendations into a new plan.Can I have multiple active plans?
Yes. Each plan lives in its own directory underdocs/justkeepswimming/.
Does the night-build work with any project?
Yes. Phase 0 discovers your stack, deployment procedure, and process manager. Only relevant phases execute.Does this work with git?
Plans and handoffs are plain markdown files. Commit, branch, share — they're just files.Apache 2.0 · Made by Qais Alkurdi