| title | First Run | ||
|---|---|---|---|
| description | Get Jumbo set up in your project and complete your first goal. | ||
| sidebar |
|
Get Jumbo initialized and complete your first goal with these simple commands:
jumbo init # Set Jumbo up
claude # Seed Jumbo with existing project knowledge
jumbo goal add # Create a goal
claude # Refine, implement, review, and codifyFull walkthrough below.
Navigate to your project directory and run:
jumbo initJumbo walks you through a short setup, then shows a plan of what it will create before asking for confirmation:
? Project name: My Project
? Purpose (optional): A short description of what this project does
? Proceed with initialization? Yes
Initializing project...
✓ Updated AGENTS.md
✓ Updated CLAUDE.md
...
✅ Welcome to Jumbo! Project initialized successfully.
projectId: project
name: My Project
Jumbo creates a .jumbo/ directory containing your project's memory store, configures agent hooks, and installs Jumbo skills. See What Jumbo Creates for the full list of files.
Start your AI coding agent. For example, with Claude Code:
claudeJumbo hooks into the session and prompts your agent to capture existing project knowledge.
:::note You might need to run an initial prompt like "Hi" or "Follow instructions" to initiate the agent. :::
The agent will read your project's AGENTS.md, run jumbo session start, and offer to capture your existing project knowledge:
❯ hi
● I can see you've added Jumbo to this project. This looks like an existing
codebase with valuable context to preserve. Would you like me to help
transfer your existing project knowledge into Jumbo? I can scan your
documentation, code structure, and patterns to capture:
- Project purpose and target audience
- Architectural components and dependencies
- Development guidelines and coding standards
- Architectural decisions from docs, comments, or ADRs
Should we start by scanning your project documentation?
:::note This example is from a brownfield project with existing code and documentation. In a greenfield project, the agent will acknowledge there is no existing context to capture and prompt you for what to work on. :::
Tell the agent to proceed:
❯ go for it
The agent will scan your project and begin registering what it finds with Jumbo — components, decisions, guidelines, dependencies, and more. Each registration requires your approval:
Bash command
jumbo component add --name "Identity & Tenant Service"
--description "Handles user authentication, RBAC, and tenant management."
This command requires approval
Do you want to proceed?
❯ 1. Yes
2. Yes, and don't ask again for: jumbo component:*
3. No
Select option 2 to auto-approve subsequent registrations of the same type, or review each one individually.
End your agent session when finished, or clear context and switch to a fresh terminal for Step 3.
:::tip[Best practice]
Archive all of your context related .md files to a location outside of your repository, and strip your AGENTS.md of any special instructions that can be registered with Jumbo. They will cause context bloat and potential conflicting instructions (as your project evolves) if left for agents to read. You can always ask an agent to port them from Jumbo to an .md later if you want to remove Jumbo.
:::
Goals are how you tell Jumbo what needs to be done. Each goal has an objective and success criteria.
Create your first goal from the terminal:
jumbo goal add \
--title "Add rate limiting" \
--objective "Add rate limiting middleware to the API" \
--criteria "Returns 429 with Retry-After header when limit exceeded" \
"Reads rate limit threshold from app configuration" \
"Rate limits configurable per route via config" \
"Bypasses health check and metrics endpoints" \
"Includes unit tests for limit exceeded scenarios"If you are using the TUI, run jumbo and press g from the primed-empty Cockpit screen to open the same goal authoring flow without leaving the interface.
You can also press m anywhere the main TUI frame owns input to open the Mega Menu. Use the arrow keys and Enter to navigate between Cockpit, Goals, Memory, and Settings. Goal menu entries such as Backlog, Active, and Archive open the Goals screen with the matching status filter already applied.
Output:
SUCCESS Goal defined
goalId: goal_01JXXXXXXXXXX
title: Add rate limiting
objective: Add rate limiting middleware to the API
criteria:
- Returns 429 with Retry-After header when limit exceeded
- Reads rate limit threshold from app configuration
- Rate limits configurable per route via config
- Bypasses health check and metrics endpoints
- Includes unit tests for limit exceeded scenarios
status: defined
Your goal is now in defined status — registered with Jumbo but not yet ready for implementation. The next step is to put your agent to work refining and implementing it.
:::note These next steps walk you through the standard Jumbo workflow for implementing goals. It is recommended to adopt advanced workflows once the basics are understood. :::
Start a fresh agent session. Jumbo presents your planned goals:
❯ hi
● Session is active. Here's where things stand:
No goals currently in progress. There is 1 planned goal in the backlog:
1. Add rate limiting middleware
Should I start with the planned goal, or do you have something else in mind?
Instruct the agent to refine the goal:
❯ refine the rate limiting goal
The agent searches Jumbo for project knowledge relevant to the goal — components, decisions, guidelines, and dependencies — and links them so the implementing agent receives precise context. When finished, the agent runs jumbo goal commit, marking the goal ready for implementation.
Clear the agent's context window or restart the session before moving to Step 4.b. Each phase works best with a fresh context window so the agent isn't carrying stale conversation history.
:::tip[Best practice] Dedicate a terminal to refinement and clear the context window after each goal. Use a model that excels at planning and deep thinking — the upfront investment in more capable models pays dividends during implementation. :::
Open a new terminal or restart your agent to get a fresh context window. The agent will greet you with your planned goals again. Instruct it to start the goal:
❯ start the rate limiting goal
The agent receives the goal's context packet from Jumbo and begins implementation. When finished, the agent runs jumbo goal submit, marking the goal ready for review.
Clear context before moving to Step 4.c.
:::note Correct the agent if it makes mistakes along the way. A mistake is likely the result of a guideline or invariant that has not been registered with Jumbo. The agent should capture the correction and propose an addition. These instances happen frequently when Jumbo is first added to a project, but decrease over time. :::
:::tip[Best practice] Dedicate a terminal to implementation. A second-tier model (e.g., Sonnet 4.6) should yield positive results if the refinement best practices are followed. :::
Open a new terminal or restart your agent. Instruct the agent to review the goal:
❯ review the rate limiting goal
The agent verifies each criterion against the implementation.
If approved, the agent runs jumbo goal approve, marking the goal ready for codification. There is typically enough context window left to continue directly to Step 4.d.
If issues are found, the agent registers them with Jumbo and runs jumbo goal reject, returning the goal for rework. Clear the context window and repeat from Step 4.b.
:::tip[Best practice] Dedicate a terminal to reviewing goals. Clear the context window after reviewing each goal. :::
After approval, instruct the agent to codify the goal:
❯ codify the goal
The agent captures new learnings, reviews registered entities for staleness, updates documentation, then closes the goal.
You've completed your first full goal lifecycle: define → refine → implement → review → codify. Every decision, guideline, and component the agent registered along the way is now part of Jumbo's memory and will inform future goals.
- What Jumbo Creates — Understand the full project footprint
- Goal Management — Learn the full goal lifecycle
- Advanced Workflows — Multi-agent workflows and productivity tips