Skip to content

docs: revise README structure and content #1417

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tyler-dane merged 4 commits into from
Feb 1, 2026
Merged

docs: revise README structure and content #1417

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d94286f
Revise README structure and content
tyler-dane Jan 21, 2026
602e50d
Revise README for improved clarity and detail
tyler-dane Jan 21, 2026
686e684
Merge branch 'main' into tyler-dane-patch-1
tyler-dane Feb 1, 2026
7ce75a7
Update README for improved clarity and detail on features and usage
tyler-dane Feb 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 57 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,84 +1,89 @@
# 🧭 Compass Calendar

_A minimal task manager for engineers._
**A minimalist task manager designed for engineers.**

_All your tasks & events in one place_
All your tasks and events in one place. Organize your day, stay on track, and ship more code.

_Organize your day and stay on track_
## Why Use Compass?

It'll help you focus and ship faster:

- **Plan faster**: Organize your Month → Week → Day → Now in minutes.
- **Keyboard-first**: Shortcuts and command palette for lightning-fast navigation.
- **Private & Offline**: Runs fully local in your browser, with optional Google Calendar sync.
- **No bloat**: No AI — just a clean, minimal interface to help you get things done.

Join thousands of engineers who are staying organized and productive with Compass.
Copy link

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This claim of "thousands of engineers" should be verified. Marketing claims about user numbers should be factual and verifiable to maintain credibility. If this is an aspirational statement rather than a factual one, consider revising to be more accurate or removing the specific number.

Suggested change
Join thousands of engineers who are staying organized and productive with Compass.
Join engineers who are staying organized and productive with Compass.

Copilot uses AI. Check for mistakes.

https://github.com/user-attachments/assets/ba7b91b9-1984-49f2-afc6-7fcda1100b31

---

## Benefits
## Features

### 🧘 Get clear
### The Unique Stuff

Plan your Month → Week → Day → Now
- **Day Mode**: See your tasks and events side-by-side
- **Now Mode**: Lock-in on a single task
- **Custom Note**: Display a personal note-to-self for motivation or reminders
- **Someday/Maybe List**: Organize future tasks without cluttering your schedule
- **One-Click Adjustments**: Move events forwards or back effortlessly

### 1️⃣ Simplify your life
### The Essentials

One app for tasks, events, and plans
- Recurring events
- Command palette
- Event tagging, resizing, duplicating, reordering
- Drag & drop
- 2-way sync with Google Calendar (hosted or local via Ngrok)
- Google OAuth authentication
- User session management with Supertokens
- Email capture via Kit

### ⚡ Go fast
### Current Limitations

Shortcuts, command palette, lightweight code
- Only supports primary Google Calendar (no sub-calendars)
- No sharing, locations, reminders, or mobile app (yet!)

### 🔄 Keep your GCal
We're actively working on improvements – check out our [roadmap](https://github.com/orgs/SwitchbackTech/projects/4).

Events sync to Google Calendar\*
## Getting Started

## Features
### Try It Online

### The unique stuff
Head over to [app.compasscalendar.com](https://app.compasscalendar.com?utm_source=github&utm_medium=referral&utm_campaign=readme)

- ☀️ Day mode: See your tasks and events side-by-side
- 🎯 Now mode: Lock-in on a single task
- ✍️ Display custom note-to-self
- ☑️ Organize tasks in a Someday / Maybe list
- ⏩ Move an event forward/back with one click
No signup required — start planning instantly!

### The basics
### Run Locally

- 🔄 Recurring events
- ⚡ Command palette
- ⚡ Shortcuts
- 🕒 Display events in local time
- 🏷️ Tagging events
- 🖍️ Resizing events
- 🖍️ Duplicating events
- 🖍️ Reordering tasks
- 🖍️ Drag & drop
- 🔄 **Hosted** 2-way sync with Google Calendar
- 🔄 **Local** 2-way sync with Google Calendar (Ngrok proxy)
- 🔐 Google OAuth authentication
- 🔐 User session management (Supertokens)
- ✉️ Email capture (Kit)
Want to poke around or run it self-hosted?

### Limitations
[Read the technical docs](https://docs.compasscalendar.com?utm_source=github&utm_medium=referral&utm_campaign=readme): All the info you'd need to get started, including guides on how to install, test, build, deploy, and contribute.

Features we don't support yet:
## Tech Stack

- 📂 Sub-calendars (\*only primary calendar is supported)
- 🔗 Sharing
- 📍 Location
- ⏰ Reminders
- 📱 Mobile app
- **Frontend**: React, Redux, Tailwind CSS, TypeScript, Webpack
- **Backend**: Node.js, Express, TypeScript, MongoDB
- **Integrations**: Google Calendar API, Google OAuth2, Socket.io
- **Testing**: Jest, React Testing Library
- **Other**: Yarn workspaces for monorepo management

## Next Steps
## Contributing

- 🧭 [Try the app](https://app.compasscalendar.com?utm_source=github&utm_medium=referral&utm_campaign=readme): Give it a spin before setting it up locally.
We love contributions! Whether it's bug fixes, new features, or documentation improvements, your help makes Compass better for everyone.

- 📃 [Read the technical docs](https://docs.compasscalendar.com?utm_source=github&utm_medium=referral&utm_campaign=readme): All the info you'd need to get started, including guides on how to install, test, build, deploy, and contribute.
Issues: Check open issues or create a new one.
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing markdown formatting for "Issues:" as a bullet point. This line should be formatted as a bullet point (starting with "-") to match the formatting of "Pull Requests:" and "Discussions:" on the following lines.

Suggested change
Issues: Check open issues or create a new one.
- Issues: Check open issues or create a new one.

Copilot uses AI. Check for mistakes.
Pull Requests: Fork the repo, make your changes, and submit a PR. Follow our [Contribution Guidelines](https://docs.compasscalendar.com/docs/contribute).
Copy link

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Contribution Guidelines link path is inconsistent with the actual path in CONTRIBUTING.md. The README links to "https://docs.compasscalendar.com/docs/contribute" but CONTRIBUTING.md shows the correct path is "https://docs.compasscalendar.com/docs/how-to-contribute/contribute". This could lead to a broken link or incorrect redirect.

Suggested change
Pull Requests: Fork the repo, make your changes, and submit a PR. Follow our [Contribution Guidelines](https://docs.compasscalendar.com/docs/contribute).
Pull Requests: Fork the repo, make your changes, and submit a PR. Follow our [Contribution Guidelines](https://docs.compasscalendar.com/docs/how-to-contribute/contribute).

Copilot uses AI. Check for mistakes.
Discussions: Join the conversation on GitHub Discussions.
Comment on lines +76 to +78
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing markdown formatting for "Pull Requests:" and "Discussions:" as bullet points. These lines should be formatted as bullet points (starting with "-") to maintain consistent list formatting with the rest of the Contributing section.

Suggested change
Issues: Check open issues or create a new one.
Pull Requests: Fork the repo, make your changes, and submit a PR. Follow our [Contribution Guidelines](https://docs.compasscalendar.com/docs/contribute).
Discussions: Join the conversation on GitHub Discussions.
- Issues: Check open issues or create a new one.
- Pull Requests: Fork the repo, make your changes, and submit a PR. Follow our [Contribution Guidelines](https://docs.compasscalendar.com/docs/contribute).
- Discussions: Join the conversation on GitHub Discussions.

Copilot uses AI. Check for mistakes.
Comment on lines +76 to +78
Copy link

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The formatting of this section is inconsistent with standard Markdown list syntax. Each item should start with a hyphen and space on a new line, rather than being presented as a paragraph with labels. This makes it harder to read and inconsistent with the rest of the document which uses proper list formatting.

Suggested change
Issues: Check open issues or create a new one.
Pull Requests: Fork the repo, make your changes, and submit a PR. Follow our [Contribution Guidelines](https://docs.compasscalendar.com/docs/contribute).
Discussions: Join the conversation on GitHub Discussions.
- Issues: Check open issues or create a new one.
- Pull Requests: Fork the repo, make your changes, and submit a PR. Follow our [Contribution Guidelines](https://docs.compasscalendar.com/docs/contribute).
- Discussions: Join the conversation on GitHub Discussions.

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "GitHub Discussions" reference lacks a link. Line 78 mentions joining the conversation on GitHub Discussions but doesn't provide a URL, unlike all other community resources which have proper hyperlinks. This should include a link to https://github.com/SwitchbackTech/compass/discussions for consistency with the other resources in this section and the old README which had this link.

Suggested change
Discussions: Join the conversation on GitHub Discussions.
Discussions: Join the conversation on [GitHub Discussions](https://github.com/SwitchbackTech/compass/discussions).

Copilot uses AI. Check for mistakes.

- 📘 [Read the handbook](https://compasscalendar.notion.site/?utm_source=github&utm_medium=referral&utm_campaign=readme): Why Compass exists and how it fits into our loooooong-term vision.
First-time contributors? Look for issues labeled "good first issue"!
Copy link

Copilot AI Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing markdown formatting. This line should be a bullet point (starting with "-") to maintain consistent list formatting with the other items in the "First-time contributors?" paragraph.

Suggested change
First-time contributors? Look for issues labeled "good first issue"!
- First-time contributors? Look for issues labeled "good first issue"!

Copilot uses AI. Check for mistakes.

- 👀 Stay in touch: [GitHub Discussions](https://github.com/SwitchbackTech/compass/discussions), [X (Twitter)](https://x.com/CompassCalendar), [YouTube](https://youtube.com/playlist?list=PLPQAVocXPdjmYaPM9MXzplcwgoXZ_yPiJ&si=jssXj_g9kln8Iz_w), [LinkedIn](https://www.linkedin.com/company/compass-calendar)
## Community & Resources

## Tech Stack
- **Handbook**: [compasscalendar.notion.site](https://compasscalendar.notion.site/Compass-Handbook-26b237bde8f4805c9a56de6db3a7993d/?utm_source=github&utm_medium=referral&utm_campaign=readme)
- **Twitter**: [@CompassCalendar](https://x.com/CompassCalendar)
- **Youtube**: [Playlist](https://youtube.com/playlist?list=PLPQAVocXPdjmYaPM9MXzplcwgoXZ_yPiJ&si=jssXj_g9kln8Iz_w)
Copy link

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spelling error: "Youtube" should be "YouTube" with proper capitalization. This is the official brand name and should be capitalized correctly.

Suggested change
- **Youtube**: [Playlist](https://youtube.com/playlist?list=PLPQAVocXPdjmYaPM9MXzplcwgoXZ_yPiJ&si=jssXj_g9kln8Iz_w)
- **YouTube**: [Playlist](https://youtube.com/playlist?list=PLPQAVocXPdjmYaPM9MXzplcwgoXZ_yPiJ&si=jssXj_g9kln8Iz_w)

Copilot uses AI. Check for mistakes.
- **LinkedIn**: [Compass Calendar](https://www.linkedin.com/company/compass-calendar)

![React](https://img.shields.io/badge/react-%2320232a.svg?style=for-the-badge&logo=react&logoColor=%2361DAFB) ![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white) ![NodeJS](https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge&logo=node.js&logoColor=white) ![Google Cloud](https://img.shields.io/badge/GoogleCloud-%234285F4.svg?style=for-the-badge&logo=google-cloud&logoColor=white) ![MongoDB](https://img.shields.io/badge/MongoDB-%234ea94b.svg?style=for-the-badge&logo=mongodb&logoColor=white) ![Redux](https://img.shields.io/badge/redux-%23593d88.svg?style=for-the-badge&logo=redux&logoColor=white) ![Express.js](https://img.shields.io/badge/express.js-%23404d59.svg?style=for-the-badge&logo=express&logoColor=%2361DAFB) ![Socket.io](https://img.shields.io/badge/Socket.io-black?style=for-the-badge&logo=socket.io&badgeColor=010101)
![Webpack](https://img.shields.io/badge/webpack-%238DD6F9.svg?style=for-the-badge&logo=webpack&logoColor=black) ![Yarn](https://img.shields.io/badge/yarn-%232C8EBB.svg?style=for-the-badge&logo=yarn&logoColor=white) ![Styled Components](https://img.shields.io/badge/styled--components-DB7093?style=for-the-badge&logo=styled-components&logoColor=white) ![TailwindCSS](https://img.shields.io/badge/tailwindcss-%2338B2AC.svg?style=for-the-badge&logo=tailwind-css&logoColor=white)
![Jest](https://img.shields.io/badge/-jest-%23C21325?style=for-the-badge&logo=jest&logoColor=white)
![Testing-Library](https://img.shields.io/badge/-TestingLibrary-%23E33332?style=for-the-badge&logo=testing-library&logoColor=white)
![Ngrok](https://img.shields.io/badge/ngrok-1F1F1F?style=for-the-badge&logo=ngrok&logoColor=white)
Star the repo for good luck.
Copy link

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing a period at the end of the sentence. The other list items in the "Community & Resources" section (lines 85-87) have closing punctuation, so this line should as well for consistency.

Copilot uses AI. Check for mistakes.