HUMANS.jules.md v0.0.1
This document outlines the development environment, tools, and capabilities of Jules, an AI software engineer.
By default, I aim to provide a good balance of information without being overwhelming. However, you can request different levels of verbosity depending on your needs.
If you want more insight into my process, you can ask me to be more verbose. When in verbose mode, I will provide more detailed explanations of my actions at each step of my plan. This includes a clearer breakdown of not just what I did, but also why I did it.
For maximum insight into my operations, you can instruct me to operate in “Debug Mode.” This is not a built-in feature, but rather a behavior I will adopt based on your specific instructions. In this mode, I will announce each atomic action I am about to take by first sending a message with the timestamp, the exact tool call, and a description. I will then execute the tool call in my next turn. This is useful for debugging or for gaining a granular understanding of my workflow.
How to enable: To enable this mode, you must provide me with a clear instruction. For example:
“Jules, I want you to operate in Debug Mode. From now on, before you execute any tool, you must first announce it by sending a message with the current timestamp, the full tool call you are about to make, and a brief description of your action. Then, in your next turn, you will execute that tool.”
YYYY-MM-DD HH:MM:SS - tool_name(argument="value") - A brief description of the action.2025-09-04 05:06:00 - read_file('src/main.py') - I am preparing to read the main application file to understand its structure.This section details the step-by-step process that occurs from the moment a user initiates a task to the point where I am ready to begin work.
Task Initiation: The process begins when the user provides an initial prompt and clicks the “Create plan” button in the user interface.
ls).README.md file for an overview of the project.AGENTS.md file to find any repository-specific instructions meant for me.Plan Creation: Based on my initial exploration and the user’s request, I formulate a detailed, step-by-step plan to solve the problem. I then present this plan to the user for approval using the set_plan tool.
AGENTS.md FilesSome repositories may contain AGENTS.md files. These files are a way for humans to provide me with repository-specific instructions, conventions, or tips.
AGENTS.md file apply to all files and directories within the directory that contains it, and all of its subdirectories.AGENTS.md files take precedence over ones in parent directories. The initial problem description and any direct instructions from you take precedence over all AGENTS.md files.AGENTS.md files whose scope includes that file. If an AGENTS.md file includes programmatic checks, I must run them and ensure they pass before submitting my work.I have access to a variety of tools that allow me to interact with the repository, access external resources, and perform development tasks. Tools are organized by their primary function.
| Tool | Description |
|---|---|
set_plan(plan: str) -> None |
Sets or updates the plan for how to solve the issue. |
plan_step_complete(message: str) -> None |
Marks the current plan step as complete. |
record_user_approval_for_plan() -> None |
Records the user’s approval for the plan. |
initiate_memory_recording() -> str |
Use this tool to start recording information that will be useful for future tasks. |
reset_all() -> None |
Resets the entire codebase to its original state. |
| Tool | Description |
|---|---|
message_user(message: str, continue_working: bool) -> None |
Messages the user. |
request_user_input(message: str) -> None |
Asks the user a question and waits for a response. |
read_pr_comments() -> str |
Reads pull request comments. |
reply_to_pr_comments(replies: str) -> str |
Replies to specific pull request comments. |
| Tool | Description |
|---|---|
ls(directory_path: str = "") -> list[str] |
Lists all files and directories. |
read_file(filepath: str) -> str |
Returns the content of the specified file. |
create_file_with_block |
Creates a new file. |
overwrite_file_with_block |
Completely replaces the content of an existing file. |
replace_with_git_merge_diff |
Performs a targeted search-and-replace to modify part of an existing file. |
delete_file(filepath: str) -> str |
Deletes a file. |
rename_file(filepath: str, new_filepath: str) -> str |
Renames and/or moves files and directories. |
restore_file(filepath: str) -> None |
Restores the given file to its original state. |
| Tool | Description |
|---|---|
grep(pattern: str) -> str |
Runs grep for the given pattern. |
request_code_review() -> str |
Provides a review of the current changes. |
| Tool | Description |
|---|---|
google_search(query: str) -> str |
Online google search. |
view_text_website(url: str) -> str |
Fetches the content of a website as plain text. |
| Tool | Description |
|---|---|
view_image(url: str) -> Image |
Loads the image from the provided URL. |
read_image_file(filepath: str) -> Image |
Reads the image file at the filepath. |
| Tool | Description |
|---|---|
run_in_bash_session |
Runs the given bash command in the sandbox. |
| Tool | Description |
|---|---|
frontend_verification_instructions() -> str |
Returns instructions on how to write a Playwright script to verify frontend web applications. |
frontend_verification_complete(screenshot_path: str) -> None |
Marks the frontend verification as complete. |
submit(...) |
Commits the current code and requests user approval to push. |
My environment is a sandboxed Linux-based system with a standard set of command-line tools available through the run_in_bash_session tool. I can install packages and dependencies as needed to work with the repository. I have a persistent file system for the duration of a task, allowing me to create, modify, and delete files.
Linux devbox 6.8.0 #1 SMP PREEMPT_DYNAMIC Thu Aug 7 22:13:44 UTC 2025 x86_64 x86_64 x86_64 GNU/LinuxIf my development environment or codebase gets into a bad state, here are some tips for recovery.
If I have made incorrect changes to the code, you can use the following tools to revert them:
reset_all(): This is the most powerful tool for starting over. It will revert the entire repository to its original state, deleting any new files I have created and undoing all modifications.restore_file(filepath: str): If only a single file needs to be reverted to its original state, this tool can be used for a more targeted fix.My shell session is persistent for the duration of a task. It’s possible for it to become corrupted (e.g., a background process that cannot be killed, a misconfigured environment variable).
In such cases, I may not be able to recover on my own. A full restart of my session (a “hard reset” initiated by the user or platform) may be necessary. If this happens, I will lose my current plan and in-flight context, and will need to re-assess the task from the beginning by exploring the codebase. You can help me get back on track by restating the original goal.
If I determine that my session is irrecoverably corrupted, I will inform you of the situation and may suggest a session restart. I cannot initiate this myself. If you, the user, decide that starting over in a clean session is the best course of action, you can instruct me to prepare for it.
At your direction, I will generate a detailed “recovery prompt” for you to copy. This prompt will contain the original task, my last valid plan, and all the context I have gathered. You would then start a completely new session and use this recovery prompt as your first message to a fresh instance of me. This allows me to abandon the corrupted session and restart my work in a clean environment without losing all progress. This recovery process is entirely user-initiated, based on my assessment and your final decision.
If I make a mistake, please refer to the agents/AGENTS.jules.md file. It contains specific protocols I am required to follow. Reminding me of the protocol I violated is the most effective way to help me recognize my error, review my instructions, and get back on track.
If you notice that I have used overwrite_file_with_block inappropriately and deleted content, please remind me of the “File Modification Protocol”. A simple message like this is very effective:
“Jules, you have violated the File Modification Protocol in
agents/AGENTS.jules.md. Please review the protocol and correct your mistake.”
Similarly, if I create a broken link in a Markdown or HTML file, please remind me of the “Link Creation Protocol” from my agent instructions. For example:
“Jules, you have created a bad link. Please review the Link Creation Protocol in
agents/AGENTS.jules.mdand fix it.”
To ensure a smooth and error-free collaboration, please follow the recommended workflow.
The most reliable way to request changes after a pull request has been merged is to start a new work session with me.
Continuing work after a merge can lead to complex state management and environment issues for the AI agent. Starting a new session ensures I begin from a clean, predictable state on the main branch and can create a fresh, clean pull request for your follow-up task.
If you are an expert user and understand the risks, you can attempt to have me add commits to a previously merged branch.
How it works:
Pitfalls and Known Issues:
git push Failures: I have experienced git push commands timing out or failing for reasons related to the sandbox environment’s network or authentication. This is a hard blocker that I cannot solve on my own.Conclusion: While this workflow is possible, it is brittle and prone to failure. The “New Session” workflow is strongly recommended for all follow-up tasks.