Projects

A project in Pensum is a markdown file with type: project in its frontmatter. That’s it. There’s no separate database, no project-specific UI for editing the file — it’s a regular note you can use however you want. Pensum just understands it as a project and gives you tools that operate on it.

This means projects are portable: they live in your vault, sync however you sync, and continue to work as plain markdown if you ever uninstall Pensum.

Creating a project

From the command palette

Run Pensum: New Project (or assign it a hotkey under Settings → Hotkeys). A modal asks for:

• Name (required) — becomes the file name and the H1 of the project file
• Status — active by default; other common values: planning, on-hold, complete, archived
• Priority — optional

Press Enter. Pensum creates the file in your Projects folder (default Projects/) from the project template.

From a template

Templates live at .pensum/templates/project.md. Edit it to change the default frontmatter, sections, or anything else. You can also add custom templates for different project types (client onboarding, sprint, OKR, whatever) — see the templates guide.

Manually

Create any markdown file with type: project in frontmatter and Pensum picks it up on the next scan:

---
type: project
status: active
created: 2026-05-16
---

The next time Pensum scans (or after Pensum: Rescan vault), the project is indexed.

How tasks belong to a project

There are two ways to assign a task to a project. Both work; you can mix them.

1. Containment

A task inside a project file automatically belongs to that project:

<!-- in Projects/Acme.md -->
- [ ] Send pricing deck to client

Pensum sees this task and, because the surrounding file is type: project, knows the task belongs to the Acme project. Project dashboards, “By Project” view, and project-page panels all include it.

2. Inline tag

A task in any file (Inbox, meeting note, daily note, etc.) can declare a project with the #project/<name> tag:

- [ ] Send pricing deck to client #project/acme

The tag value matches the project file’s name (without the .md extension), case-insensitively.

Inline tags win over containment. If a task is inside Projects/Acme.md but tagged #project/beta, the task belongs to Beta. This means meeting notes can carry tasks that get assigned to projects without moving the task out of the meeting note.

When to use which

• Containment is the default for proper project tasks. Edit the project file, add tasks, done.
• Inline tags are best for tasks that have a natural home elsewhere — meeting tasks belong to the meeting, but should still roll up to the project for visibility.

The Smart Triage flow uses both: for inbox tasks, accepting a suggestion moves the task into the project file (containment). For meeting-extracted tasks, accepting a suggestion adds the tag (the task stays in the meeting note).

Project Page panel

The Project Page is a sidebar panel that auto-opens when you view a project file. It runs alongside the project’s markdown content so you can see the file and its dashboard side-by-side.

What’s in the panel

• Title — the project file’s name
• Frontmatter fields — status, priority, and any custom fields you’ve added (client, owner, team, etc.). Pensum displays whatever’s in the frontmatter; there’s no fixed schema.
• Stats — open task count, overdue count, completed in the last 7 days
• Open tasks — the project’s open task list, sorted by priority and due date, clickable
• Overdue tasks — pulled out as their own list so they’re visible
• Recently completed — last 7 days, with completion dates

The panel updates live as you edit tasks anywhere in your vault. Complete a task → the stats refresh, the task moves to “Recently completed.”

When the panel auto-opens

Whenever you open any file with type: project in frontmatter. If you close the panel, it stays closed until you open a different project file. You can also force-open it via Pensum: Open project page panel in the command palette.

By Project view

Open via the command palette: Pensum: Open by project view.

Shows every open task across your vault, grouped by project. Each project section is collapsible. Click any task to edit.

Useful when you want a single-screen read of “what’s open everywhere” without opening each project file.

Frontmatter conventions

Pensum doesn’t enforce a frontmatter schema for projects — use whatever fields you want. The Project Page panel will render any field you add. Common conventions:

---
type: project
status: active            # active | planning | on-hold | complete | archived
priority: high            # highest | high | medium | low | lowest
created: 2026-05-16
owner: jamie
team: revenue
client: acme-corp
tags: [revenue]
related: [[Q3 Forecast]]
---

Filters and queries (Filters view, CLI, MCP) operate over these fields generically — if you put customer: acme in frontmatter, you can filter by it.

Customising the project template

Edit .pensum/templates/project.md to change what new projects look like. The default template has:

---
type: project
status: {{status}}
created: {{created}}
priority: {{priority}}
tags: []
related: []
---

# {{name}}

> Short description.

## Goals
-

## Open questions
-

## Tasks

- [ ]

## Notes

Common customisations:

• Add team / owner / customer fields with prompts
• Add a “Recently completed” section that’s auto-populated by some other plugin
• Replace the section structure with something specific to your workflow (Eisenhower-style: Important / Urgent / Backlog)

See templates for full template syntax including prompt_for for custom variables.

Archiving and completing projects

Pensum doesn’t move project files automatically when their status changes — they stay where they are. To archive a project:

• Set status: archived in frontmatter, or
• Move the file to an Archive/ folder of your choice

Either way, the project still exists in your vault and tasks still resolve correctly. The By Project view shows all projects with open tasks; an archived project with no open tasks doesn’t show up there.

What’s not in v1.0

• Cross-project task aggregation beyond the By Project view (e.g. “all tasks across projects A, B, C with priority high”) — use the Filters view for this in v1.0.
• Project templates with subprojects — you can build the structure manually; no built-in support.
• Project Page editing of frontmatter — for now you edit the file directly. A UI for common fields is on the post-launch roadmap.