| name | netclaw-projects |
| description | How to create, find, and work with project workspaces. Load when the user references a project, asks to organize work, or you need a sustained workspace. |
| metadata | {"author":"netclaw","version":"1.2.0"} |
| license | MIT |
| compatibility | netclaw >= 0.10.0 |
| disable-model-invocation | false |
Project Workspaces
A project is a local git repo with an AGENTS.md at its root. Projects
live in your workspaces directory (check TOOLING.md for the path).
Projects can be nested at any depth within the workspaces directory. A cloned
engineering repo counts. So does a directory you create for a marketing campaign,
research initiative, or any sustained body of work.
Finding Existing Projects
Before creating a new project, always check what already exists:
shell_execute("find <workspaces_path> -name AGENTS.md -maxdepth 4 -type f")
Read the AGENTS.md of any match to understand its purpose. If a project
already covers the user's request, cd into it and work there.
Creating a New Project
Only create a project when:
- The work is sustained (multi-session, ongoing)
- No existing project covers it
- The user explicitly asks to start one
Steps:
- Choose a descriptive directory name (kebab-case)
shell_execute("mkdir -p <workspaces_path>/<name> && cd <workspaces_path>/<name> && git init")- Write an
AGENTS.md with file_write describing:
- What this project is about
- Goals and constraints
- Relevant context (target audience, products, tools, etc.)
shell_execute("cd <workspaces_path>/<name> && git add -A && git commit -m 'Initial project setup'")
The AGENTS.md is the project's living context document. Update it as the
project evolves.
Working in a Project
When you start working on a project, use set_working_directory to set the
project directory:
set_working_directory(path: "/home/user/workspaces/my-project")
This automatically loads the project's identity file (.netclaw/AGENTS.md,
CLAUDE.md, AGENTS.md, or CONTEXT.md — first match wins) into the system
prompt. The project context persists across crash/restart, so you don't need to
re-read it manually.
Use the project directory as your working directory for all project-related
file operations. Commit meaningful changes so the project has history.
Team and Personal sessions refresh Git working context at the beginning of a
turn. That snapshot is grounding, not a live view: changes made during the turn
appear in the next turn. A spawned subagent receives its own read-only snapshot
and reports only changes confirmed through its tools. Do not infer that every
dirty file in the shared worktree was changed by that subagent.
When NOT to Create a Project
One-off tasks don't need a project. If the user asks a quick question, runs a
single search, or needs something done once — just do it in the current session.
Don't create overhead for throwaway work.
