Projects

Projects give Toby a durable workspace for a specific body of work. A project has its own folder, instructions, project chats, generated outputs, optional persona, and project-local skills so related work stays together across sessions.

What a project is

A project is a record in Toby's local session database backed by a folder under ~/.toby/projects/. New projects use a stable project id for the folder name, and Toby.app exposes the exact path from the project inspector.

~/.toby/projects/<project-id>/
  AGENTS.md          # project instructions read by project chats
  .agent/skills/     # project-local skills
  outputs/           # generated artifacts

When you work inside a project, Toby uses the project metadata and folder contents to keep the chat grounded:

1. Project guidance — AGENTS.md is included as project-specific instruction.
2. Project-local skills — every SKILL.md under .agent/skills/ is loaded automatically for that project.
3. Output scoping — generated files land in the project's outputs/ folder by default.
4. Project chat grouping — project chats appear under the project in Toby.app so the conversation history and workspace stay together.

This makes projects ideal for recurring workflows like weekly overviews, monthly reports, or any task where you want the AI to produce consistent output informed by the same reference material each time.

Create a project

In Toby.app, open Projects from the sidebar and click +. Toby creates the project folder, selects the project, and shows the project inspector.

Project workspace

The Projects window combines three areas:

Area	What it does
Project sidebar	Lists projects, summaries, and project chats. Select a project or jump between chats.
Chat workspace	Runs chats scoped to the selected project. Click New Chat to start another project chat.
Inspector	Edits the project name, persona, folder path, and file tree. Shows the first paragraph of the summary; Edit opens a markdown editor to change the full summary.

The project persona is optional. When set, new project chats use that persona by default, which is useful when a project always needs a specific voice or role.

Add project instructions

Every project starts with an AGENTS.md file:

~/.toby/projects/<project-id>/AGENTS.md

Use this file for durable guidance that should apply to all project chats: goals, conventions, customer context, output formats, or source-of-truth links.

Add project-local skills

Skills placed in the project's .agent/skills/ directory are loaded automatically whenever that project is active:

~/.toby/projects/<project-id>/.agent/skills/
  weekly-update-format/SKILL.md

Ask Toby to create a skill while working in a project, or add a SKILL.md manually. Project-local skills are best for instructions that should not apply globally.

Global skills under ~/.toby/skills/ still work normally. Use project-local skills when the behavior belongs only to one project.

Browse project files

The inspector shows the project file tree. Use it to confirm that generated outputs and skills landed in the right place. The folder row reveals the project folder in Finder, and files in the tree can be opened with their default app.

Generated files are written to:

~/.toby/projects/<project-id>/outputs/

When no project is active, generated files fall back to ~/.toby/generated-files/.

Use projects with schedules

Schedules can be associated with a project. When a scheduled prompt runs with a project selected, Toby uses that project's guidance and writes generated artifacts to the project workspace.

This is useful for recurring reports, weekly reviews, customer updates, and other repeated workflows that should keep the same context over time.

Legacy context folders

Older Toby project folders may contain a context/ directory or project.json. Toby migrates legacy projects into the current project database and keeps the old paths available for compatibility, but new project guidance should go in AGENTS.md and project-local skills should go under .agent/skills/.

Example: weekly overview project

# 1. Create the project
Toby.app → Projects → + → rename to "Weekly Updates"

# 2. Add durable guidance
Open the project folder from the inspector and edit AGENTS.md.

# 3. Create a skill for consistent formatting
"Create a skill called weekly-overview-format that formats a weekly status
 update with sections: Accomplishments, Blockers, Priorities Next Week.
 Write it in a concise bullet-point style."

# 4. Keep the skill project-local
Save the skill under .agent/skills/weekly-overview-format/SKILL.md.

# 5. Generate each week
"Generate this week's overview based on my recent emails and tasks"
→ output lands in the project's outputs/ folder.

Over time, the outputs/ folder accumulates each weekly overview, all produced with the same style and project instructions.

Projects vs chat history

	Chat session	Project
Stores	Conversation transcript	Instructions, skills, and generated artifacts
Primary location	~/.toby/chat.sqlite	~/.toby/projects/<project-id>/
Lifespan	Per session	Until you delete the project
AI access	Prior messages	Project guidance and project-local skills

Related

• Skills — reusable instructions, including project-local skills
• Personas — who Toby is being (complements project guidance)
• Memories — durable facts, separate from project guidance
• Schedules — automate recurring project workflows