<a id="readme-top"></a>

<div align="center">

Strategic Thinking + Execution

Most AI tools do tasks. Jules thinks with you first, then does everything else.

An open source reference implementation built on [Claude Code][claude-code-url].

[![License: MIT][license-shield]][license-url] [![Skills: 17][skills-shield]][skills-url] [![Hooks: 5][hooks-shield]][hooks-url] [![Token Savings: 60-90%][tokens-shield]][rtk-url]

[Website][website-url] · [Overnight Batch][overnight-url] · Get Started

</div>

---

<details> <summary><strong>Table of Contents</strong></summary>

• The Problem
• What Jules Does
• The Loop in Action
• Build Your Own
• Under the Hood
• Architecture
• Skills
• Hooks
• Cloud Batch
• Security & Privacy
• Evolution
• Design Decisions
• Acknowledgments
• License

</details>

---

The Problem

Running a business is a continuous loop across a dozen domains — strategy, code, content, ops, finance, people. AI helps you go faster, but speed on individual tasks doesn't move the ball forward.

You still think alone. You lose context at every tool boundary. The strategic thread connecting Tuesday's decision to Friday's deploy lives only in your head.

The hard part isn't execution. It's thinking clearly and keeping everything connected.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

What Jules Does

<table> <tr> <td width="50%" valign="top">

Thinks With You

Strategy, decisions, challenging assumptions, decomposition. Socratic dialogue, adversarial review. The cofounder you don't have.

• Surfaces blind spots and second-order effects
• Disagrees when it sees a better path
• Connects today's work to long-term goals

</td> <td width="50%" valign="top">

Then Executes

Software, content, research, deploys, analytics — one system, same context. Decisions flow directly from thinking to execution. No context loss between "what" and "build it."

• Ships code, publishes content, manages projects
• Handles the details so you focus on direction

</td> </tr> </table> <p align="right">(<a href="#readme-top">back to top</a>)</p>

The Loop in Action

Think → Build → Ship

| Step | Prompt | What Happens | |:----:|--------|-------------| | Think | "I need to figure out my brand positioning." | Jules challenges the framing, asks one question at a time, runs adversarial review. We land on a direction together. | | Build | "Now implement it." | Jules writes the homepage copy, updates the meta tags, adjusts the CSS, takes screenshots, iterates until it's right. | | Ship | "Deploy it." | Build passes. Site goes live. Jules verifies the deployment. Session report captures what changed and why. |

Think → Write → Distribute

| Step | Prompt | What Happens | |:----:|--------|-------------| | Think | "This article isn't landing. What's wrong?" | Jules reads the draft, identifies structural problems, proposes a different angle. We debate it. | | Write | "Rewrite it with that framing." | New draft, same voice calibration, same style guide. Runs a slop audit to catch AI writing patterns. | | Distribute | "Post it." | Publishes to the site, adapts for Reddit and LinkedIn, queues the cross-posts. One command. |

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Build Your Own

[!TIP] You don't need dozens of configurations to start. Try this one prompt.

Open Claude Code in your project directory and paste:

Analyze my current Claude Code setup (CLAUDE.md, .claude/ directory, and codebase) and
compare it against the reference implementation at https://github.com/jonathanmalkin/jules.

1. Read my existing configuration and understand my project, workflow, and goals.
2. Fetch and study the Jules repo README, CLAUDE.md, profiles/, .claude/hooks/,
   .claude/skills/, and docs/overnight-batch.md to understand the patterns.
3. Identify the highest-impact improvements I could make, prioritized by:
   - What I'm missing entirely (e.g., no safety hooks, no decision framework)
   - What I have but could strengthen (e.g., thin CLAUDE.md, no agent personality)
   - What's in Jules that doesn't apply to my situation (skip these)
4. Give me a concrete, prioritized action plan. Start with 2-3 changes I can make today.

Don't try to replicate the whole system. Tell me what would actually help MY setup.

Start small. The system grew organically over weeks of daily use.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Under the Hood

^{For the builders who want to know how it's made.}

| | What | Details | |:-:|------|---------| | 17 | Skills | /think, /build, /write, /research, /debug. Multi-phase workflows, not single prompts. | | 5 | Hooks | Unified safety guard, RTK token optimization, desktop notifications, session-start sync. | | 1 | Cloud Batch | Overnight: daily retro, morning briefing, email fetch. Ready before the laptop opens. | | 3 | Environments | Mac, Claude Web, Telegram. No VPS, no Docker, no daemons. | | 60-90% | Token Savings | [RTK][rtk-url] rewrites dev commands for massive context savings. | | <500 | Lines in CLAUDE.md | Identity, routing, authority, safety. One file, always loaded. |

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Architecture

Environments

┌─────────────────────┐     ┌─────────────────────────────────┐     ┌─────────────────────┐
│                     │     │          Claude Web              │     │                     │
│   Mac               │     │                                 │     │   Telegram           │
│   Interactive Dev   │     │  Scheduled    │   Interactive   │     │   Phone Access       │
│                     │     │  Batch        │   Sessions      │     │                     │
└─────────────────────┘     └─────────────────────────────────┘     └─────────────────────┘

Five-Layer Model

┌─────────────────────────────────────────────────────────┐
│  Layer 5: Products         The apps being shipped       │
├─────────────────────────────────────────────────────────┤
│  Layer 4: Automation       Cloud batch (retro,          │
│                            briefing, email)             │
├─────────────────────────────────────────────────────────┤
│  Layer 3: Configuration    CLAUDE.md + Skills + Hooks   │
├─────────────────────────────────────────────────────────┤
│  Layer 2: Operational      Terrain, Briefing,           │
│           State            Documents                    │
├─────────────────────────────────────────────────────────┤
│  Layer 1: Identity         Agent profile, user          │
│                            profile, goals               │
└─────────────────────────────────────────────────────────┘

Identity is the foundation. Products are what get shipped. Everything in between connects them.

Classification Principle

How to decide where a behavior belongs:

| If the behavior is... | It's a... | |---|---| | Pattern-matchable, no judgment needed | Hook — deterministic, fires on tool calls | | A repeatable procedure with defined inputs/outputs | Script — invoked by skill, hook, or Cloud task | | Requires AI judgment, dialogue, or synthesis | Skill — structured conversation | | A behavioral rule or preference | CLAUDE.md section — loaded every session | | Stable identity and context | Profiles/ — loaded every session |

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Skills (17)

| Skill | What It Does | |-------|-------------| | think | Recursive decomposition + advisory. Altitude system for goals, adversarial review for decisions. | | build | Software dev end-to-end: scope, plan, execute, deploy. | | write | Content production: seed to platform-ready output across all channels. | | research | Standalone research with persistence and cross-session pickup. Living documents. | | debug | Systematic debugging: hypothesize, test, narrow. | | replies | Check X mentions, draft replies, post approved ones. | | good-morning | Interactive walkthrough of the morning briefing (10 sections). | | wrap-up | End-of-session: issue capture, report, ship. 3 phases. | | stop-slop | Structural audit for AI writing patterns. | | pdf | PDF operations. | | plane | Plane.so interface: MCP tools + gap scripts + reconciliation. | | send-email | Send email via Resend. | | financial-advisor | Personal finance planning. | | generate-image-openai | Image generation with iterative two-phase workflow. | | search-history | Search session documents. | | skill-creator | Create and modify skills. | | agent-browser | Browser automation. |

Hooks (5)

Hooks are deterministic. The LLM doesn't decide whether to run them — they fire on every matching tool call.

| Hook | Trigger | What It Does | |------|---------|-------------| | safety-guard.sh | PreToolUse: Bash, WebFetch, Write, Edit | Unified security: command blocking, secret scanning, financial data guard, domain blocking | | notify-input.sh | PostToolUse | Desktop notification when agent needs input | | rtk-rewrite.sh | PreToolUse: Bash | RTK token optimization rewrites (60-90% savings on dev operations) | | session-start.sh | SessionStart | Git pull on session open |

Cloud Batch

One overnight task, three sequential phases:

| Phase | What It Does | |-------|-------------| | Retro + Memory | Analyze recent sessions, propose CLAUDE.md changes, prune stale items | | Morning Briefing | Assemble 10-section briefing from Plane, Reddit, Gmail, git log, retro output | | Email Fetch | Pull and categorize inbox |

Full implementation guide: docs/overnight-batch.md

<p