What it is
Every project Piye works on gets a .piye folder at its top. It holds Piye's notes about the project, so Visual, Code and Piye Studio read the same facts, and so they travel with the project. Your code never depends on it: delete it and the project still builds and runs.
What's inside
| Path | What it holds | Yours to edit |
|---|---|---|
project.json | The project's choices from the new project card: name, platforms, look, languages | Through Piye |
blueprint.json | The Blueprint's layout | Through Piye |
plan.json | The plan agreed in Architect | Through Piye |
rules.md | Instructions for the agent in this project | Yes |
rules/ | Rule files, including working-rules.md, the rules the agent saved at your request | Yes |
skills/ | Skills for this project (each a folder with a SKILL.md) | Yes |
skills.json | Which skills are switched off for this project | Through Piye |
settings.json | This project's settings, over yours | Yes |
keybindings.json | This project's keyboard shortcuts | Yes |
launch.json | Run and debug configurations | Yes |
mcp.json | MCP servers for this project | Yes |
memory/ | Chats, the agent's notes (notes.md) and what Piye learned about the project | No |
outbox/ | Emails and texts your app sent while you build | No |
handoff/ | What Handoff prepared, like the Blueprint picture for the brief | No |
brief/ | Files you attached to the new project card, like your logo | No |
Other files appear as you use Piye's features (for example the store page's pictures when you publish a phone app).
What to commit
- Commit the files you'd want a teammate to have:
rules.md,rules/,skills/,settings.json,keybindings.json,launch.json,project.jsonandblueprint.json. - Never commit
memory/: it holds your chats. Piye gives it its own.gitignore, and Handoff never sends it.
Other tools' files
Piye also reads the instruction files other tools use, so a project set up for them works here too: AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md, .cursor/rules/ and .claude/rules/, and skills in .claude/skills/ and .agents/skills/. See Rules, memory and skills.