| 1 | # Projects |
| 2 | |
| 3 | Projects tell Agent Zero what world it is working in. |
| 4 | |
| 5 | Use a project when you want a chat to have its own purpose, instructions, files, |
| 6 | memory, secrets, and model choices. A project can be a client, a codebase, a |
| 7 | research topic, a recurring workflow, or any other focused workspace. |
| 8 | |
| 9 |  |
| 10 | |
| 11 | ## When To Use One |
| 12 | |
| 13 | Create a project when you want Agent Zero to remember context that should not |
| 14 | leak into every other chat. |
| 15 | |
| 16 | Good project examples: |
| 17 | |
| 18 | - A Git repository you want Agent Zero to work on. |
| 19 | - A client workspace with its own tone, files, and credentials. |
| 20 | - A research topic with its own sources and notes. |
| 21 | - A recurring report that always follows the same steps. |
| 22 | - A documentation workspace with a clear writing style. |
| 23 | |
| 24 | Stay in a normal chat when the task is quick, disposable, or unrelated to a |
| 25 | larger body of work. |
| 26 | |
| 27 | ## Open Projects |
| 28 | |
| 29 | From the dashboard, click **Projects**. |
| 30 | |
| 31 |  |
| 32 | |
| 33 | If you have no projects yet, the list starts empty and offers **Create |
| 34 | project**. |
| 35 | |
| 36 |  |
| 37 | |
| 38 | ## Create A Project |
| 39 | |
| 40 | Click **Create project** and give it a clear title. The title is what you will |
| 41 | recognize later in the project picker. |
| 42 | |
| 43 |  |
| 44 | |
| 45 | For a simple project, the title is enough. If you want Agent Zero to clone a |
| 46 | repository into the project, paste the Git URL in **Git Repository** before you |
| 47 | continue. |
| 48 | |
| 49 | After creating the project, Agent Zero opens the edit screen. |
| 50 | |
| 51 | ## Write Helpful Instructions |
| 52 | |
| 53 | The most important part of a project is the **Instructions** field. |
| 54 | |
| 55 | Description answers: "What is this project?" |
| 56 | |
| 57 | Instructions answer: "How should Agent Zero behave when this project is active?" |
| 58 | |
| 59 |  |
| 60 | |
| 61 | Good instructions are usually short and specific. Tell Agent Zero: |
| 62 | |
| 63 | - what the project is for, |
| 64 | - what style of answer you want, |
| 65 | - where files should be read or written, |
| 66 | - what quality rules matter, |
| 67 | - when it should ask before acting. |
| 68 | |
| 69 | Example: |
| 70 | |
| 71 | ```markdown |
| 72 | You are working inside the Docs Example Workspace. |
| 73 | |
| 74 | Use this project for small documentation examples and user-facing guidance. |
| 75 | |
| 76 | When this project is active: |
| 77 | - Explain steps in plain language before technical detail. |
| 78 | - Prefer screenshots, checklists, and concrete examples. |
| 79 | - Keep generated files inside this project unless I ask otherwise. |
| 80 | - Ask before using credentials, private data, or external accounts. |
| 81 | - When editing docs, focus on what the user sees and what they should do next. |
| 82 | ``` |
| 83 | |
| 84 | That is enough. A project prompt does not need to be a constitution. Start small, |
| 85 | then improve it when you notice what the agent should do differently. |
| 86 | |
| 87 | ## Activate A Project |
| 88 | |
| 89 | Open or create a chat. In the top-right corner, click the project picker. It may |
| 90 | say **No project** if the chat is not attached to a project yet. |
| 91 | |
| 92 |  |
| 93 | |
| 94 | Choose your project. |
| 95 | |
| 96 |  |
| 97 | |
| 98 | When the project name appears in the top bar, the chat is now using that |
| 99 | project. Agent Zero will use the project instructions and work with the project |
| 100 | workspace for that chat. |
| 101 | |
| 102 | Each chat can use a different project. This lets you keep a client chat, a code |
| 103 | chat, and a research chat separate at the same time. |
| 104 | |
| 105 | Projects can also own Agent Profile overrides and availability. In **Manage |
| 106 | agents**, select a project before editing or turning a profile off; the Global |
| 107 | profile remains unchanged. See [Agent Profiles](agent-profiles.md). |
| 108 | |
| 109 | ## What Changes After Activation |
| 110 | |
| 111 | When a project is active, Agent Zero can use: |
| 112 | |
| 113 | - the project instructions, |
| 114 | - files stored in the project workspace, |
| 115 | - project memory, |
| 116 | - project variables and secrets, |
| 117 | - project-specific model settings when configured. |
| 118 | |
| 119 | Try prompts like: |
| 120 | |
| 121 | ```text |
| 122 | Read the project instructions and tell me how you will work in this workspace. |
| 123 | ``` |
| 124 | |
| 125 | ```text |
| 126 | Create a short README for this project based on its current files. |
| 127 | ``` |
| 128 | |
| 129 | ```text |
| 130 | Use this project as the home for our weekly research notes. |
| 131 | ``` |
| 132 | |
| 133 | ## Git Projects |
| 134 | |
| 135 | If you paste a Git repository URL while creating the project, Agent Zero clones |
| 136 | that repository into the project workspace. |
| 137 | |
| 138 |  |
| 139 | |
| 140 | Use Git projects when you want Agent Zero to work on a real codebase with the |
| 141 | right local files, branch state, and project instructions. |
| 142 | |
| 143 | For private repositories, use a token when the UI asks for one. Do not paste |
| 144 | tokens into chat messages. |
| 145 | |
| 146 | ## Variables And Secrets |
| 147 | |
| 148 | Projects can store values that only make sense inside that workspace. |
| 149 | |
| 150 | Use **variables** for non-sensitive settings, such as: |
| 151 | |
| 152 | ```text |
| 153 | REPORT_FORMAT=markdown |
| 154 | DEFAULT_REGION=eu-west |
| 155 | ``` |
| 156 | |
| 157 | Use **secrets** for credentials, such as API keys and passwords. Refer to them by |
| 158 | name in chat: |
| 159 | |
| 160 | ```text |
| 161 | Use the project GITHUB_TOKEN to check the repository status. |
| 162 | ``` |
| 163 | |
| 164 | Keep your own copy of important secrets. Backups may not include every secret. |
| 165 | |
| 166 | ## Keep Projects Tidy |
| 167 | |
| 168 | A good project stays useful because it stays focused. |
| 169 | |
| 170 | - Use a clear title. |
| 171 | - Keep instructions short enough to read. |
| 172 | - Store files where the project expects them. |
| 173 | - Keep secrets scoped to the project that needs them. |
| 174 | - Update instructions when your workflow changes. |
| 175 | - Create a new project when the work belongs to a different client, codebase, or topic. |
| 176 | |
| 177 | ## Common Problems |
| 178 | |
| 179 | **Agent Zero ignores the project.** |
| 180 | Check the top-right project picker. The project name must be visible in the |
| 181 | active chat. |
| 182 | |
| 183 | **The project instructions are wrong or stale.** |
| 184 | Open **Projects**, click the edit icon, update the instructions, and save. |
| 185 | |
| 186 | **A Git repository did not clone.** |
| 187 | Check the URL, authentication token, and network access. For private repos, |
| 188 | create a fresh token and try again. |
| 189 | |
| 190 | **Secrets are not being used.** |
| 191 | Make sure the secret is saved in the project and refer to it by exact name. |
| 192 | |
| 193 | **The project has become too broad.** |
| 194 | Split it. Projects work best when each one has a clear job. |
| 195 | |
| 196 | ## Related |
| 197 | |
| 198 | - [Usage Guide](usage.md) |
| 199 | - [Browser Guide](browser.md) |
| 200 | - [A0 CLI Connector](a0-cli-connector.md) |
| 201 | - [DeepWiki for Agent Zero](https://deepwiki.com/agent0ai/agent-zero) |