A self-hosted web app for daily standup preparation, project tracking, and AI-powered research guidance. Track what you worked on, plan what's next, manage blockers and asks, import GitHub activity, generate summaries, and get structured project critiques — all in one place.
- Four-section entries: Updates, Impact/Plans, Blockers, and Asks — structured for standup meetings
- Sub-items: Nest details under any item for hierarchical organization
- People tagging: Link team members to specific items (auto-matched from GitHub PRs)
- Auto-save: Changes save automatically 3 seconds after you stop typing
- Carry-forward: Unresolved blockers and asks carry forward to the next day with visual indicators
- Item resolution tracking: Mark blockers/asks as resolved; status tracked across days and in weekly summaries
- Soft delete & restore: Accidentally delete an entry? Undo within 30 seconds
- Drag-and-drop reordering: Rearrange items and sub-items by dragging
- Activity import: Automatically pull your authored and reviewed PRs across subscribed repos
- Issue tracking: Import open/closed issues with smart categorization (closed → updates, open → impact/asks)
- PR review comment blockers: Review comments on your PRs/issues are imported as blockers with AI-summarized sub-items
- Linked repositories: Link additional repos to projects for cross-repo activity tracking
- PR commit summaries: AI-generated summaries of PR changes
- Deduplication: Import the same day multiple times without creating duplicates (keyed by PR/issue number)
- People matching: GitHub usernames auto-matched to your collaborators list
- PR/Issue previews: Hover to preview PR and issue details inline
- Daily pitch: Generate a concise standup summary from your entries using GitHub Copilot CLI
- Weekly summary: Aggregates the full week with resolved blocker/ask tracking — shows what was resolved and when
- Attachment summarization: Upload text files and get AI-generated bullet-point summaries
- Smart caching: Summaries are cached by content hash; regenerated only when entries change
- Model selection: Choose your preferred Copilot model per user (default: claude-opus-4.6)
- Async critique generation: Launch background critique tasks that run while you navigate the app
- Research-guided reviews: Compares your project against recent academic papers and industry work (via Semantic Scholar, arXiv, DuckDuckGo)
- Structured feedback: Strengths, weaknesses, future risks, and comparisons with related work — not a paper review, but research guidance
- Project attachments: Attach links and PDFs to projects; content is included in critique context
- Critique history: View past critiques with full detail and generation logs
- Multi-project support: Track work across multiple projects with per-project metadata
- Project creation: Create projects with name, Git URL, review branch, and repo subscriptions
- Project subscriptions: Subscribe to projects to filter your view
- Sprint tracking: Create sprints and associate entries with sprint periods
- Project feed: Aggregated timeline of all entries for a project across team members
- Project settings: Configure Git URL, review branch, and project-specific settings with visual card layout
- Archive & restore: Archive projects (including all items and sub-items) and restore them later; indexed by Git identifier
- Collaborator management: Add, edit, and remove collaborators with name and optional GitHub handle
- Auto-imported handles: GitHub handles discovered during PR/issue import appear automatically
- Name mapping: Assign display names to auto-imported GitHub handles for readable references
- Per-user isolation: Each user manages their own collaborator list
- File uploads: Attach files to journal entries (per section) or to projects
- Link attachments: Add web links to projects with auto-fetched titles
- Download & preview: Download attached files directly from the UI
- Copy across sections: Move attachments between entry sections
- Full-text search: Search across all entries by content, project, or person
- Analytics dashboard: Visual breakdown of entries by project, section, and date range
- Weekly markdown export: Export a week's entries as formatted markdown
- JSON backup: Full export/import for data portability (includes entries, projects, linked repos, sprints, and people)
- User registration & login: Email-based accounts with password hashing
- Display name: Set an optional display name shown across the app (defaults to username)
- Email confirmation: Optional email verification flow
- GitHub OAuth: Link your GitHub account for seamless API access
- Per-user isolation: Each user's entries, summaries, and preferences are private
- Profile modal: Manage display name, GitHub link, password, AI model, scrum timer, and data backup — all from a single modal
- Dark mode: Toggle between light and dark themes (persisted in localStorage)
- Responsive modals: All modals use 90% parent width with scrollable content
- Standup timer: Built-in countdown timer with configurable duration (set in profile)
- Keyboard shortcuts: Ctrl+S to save, Escape to close modals
- Desktop notifications: Reminders at configurable intervals before standup
- Markdown rendering: Write entries in markdown with live preview
- Collapsible content: Long items auto-collapse with expand/collapse toggle
- Favicon: Custom SVG favicon with journal, AI, and refresh iconography
- Python 3.11+
- Node.js 18+ (for running JavaScript tests only)
- GitHub Copilot CLI (optional, for AI features)
- GitHub CLI (
gh) (optional, for GitHub integration)
cd scrum-journal
# Create virtual environment (first time only)
python3 -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Launch the app
python app.py
# Open http://localhost:5555The app uses SQLite by default — no database setup needed. A journal.db file is created automatically on first run.
Use the automated setup script to install MySQL, create the database, and optionally migrate from an existing SQLite database:
# Basic setup (prompts for password and db name/user interactively)
./scripts/setup_with_mysql.sh
# With all options specified
./scripts/setup_with_mysql.sh --db-name scrum_journal --db-user scrum_user --db-pass mypassword
# Import from an existing SQLite file (local path or URL)
./scripts/setup_with_mysql.sh --db-pass mypassword --import-db /path/to/journal.db
./scripts/setup_with_mysql.sh --db-pass mypassword --import-db https://example.com/journal.dbThe script will:
- Install MySQL server if not present
- Create the database and user
- Install Python dependencies (
mysql-connector-python) - Write
DATABASE_URLto.env(auto-loaded by the app) - Initialize the schema
- Migrate data from SQLite if
journal.dbexists (or from--import-dbsource)
The app also supports PostgreSQL and MSSQL via the DATABASE_URL environment variable:
# PostgreSQL
export DATABASE_URL=postgresql://user:pass@localhost/scrum_journal
# MSSQL
export DATABASE_URL=mssql://user:pass@server/scrum_journalOr add DATABASE_URL=... to a .env file in the scrum-journal/ directory.
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5555 app:appPlease see SETUP GUIDE for detailed instructions.
- Throughout the day — jot down updates as you work. Auto-save kicks in 3 seconds after you stop typing. Desktop notifications nudge you hourly.
- Import GitHub activity — click the GitHub import button to pull in your PRs, issues, and review comments for the day.
- Before standup — review your entry, generate a daily summary with one click.
- In standup — use the preview modal or open the summary in a new tab. Start the timer.
- End of week — generate a weekly summary that tracks resolved blockers and asks across all five days.
Helper scripts in scripts/ for automation:
| Script | Purpose |
|---|---|
setup_with_mysql.sh |
Full MySQL setup, schema init, and SQLite migration |
init_mysql_schema.py |
Initialize MySQL schema (standalone) |
migrate_sqlite_to_mysql.py |
Migrate data from SQLite to MySQL |
generate-pitch.sh |
Pre-generate daily summary via API (cron-friendly) |
generate-weekly-pitch.sh |
Pre-generate weekly summary via API (cron-friendly) |
remind.sh |
Desktop notification reminder (Linux/macOS, cron-friendly) |
# Daily summary at 11:25 AM weekdays
25 11 * * 1-5 /path/to/scripts/generate-pitch.sh
# Weekly summary every Tuesday at 10:45 AM
45 10 * * 2 /path/to/scripts/generate-weekly-pitch.sh
# Hourly reminder during work hours
0 9-17 * * 1-5 DISPLAY=:0 /path/to/scripts/remind.sh hourly
# Pre-scrum reminder at 11:20 AM
20 11 * * 1-5 DISPLAY=:0 /path/to/scripts/remind.sh scrum| Shortcut | Action |
|---|---|
Ctrl+S / ⌘+S |
Save entry |
Escape |
Close any open modal |
| Layer | Technology |
|---|---|
| Backend | Python 3.12, Flask, Flask-Login |
| Database | SQLite (default), MySQL, PostgreSQL, MSSQL |
| Frontend | Vanilla HTML/CSS/JS (no frameworks) |
| AI | GitHub Copilot CLI |
| GitHub | GitHub CLI (gh) + REST/GraphQL API |
| Testing | pytest + pytest-cov (Python), Jest + jsdom (JavaScript) |
| CI | GitHub Actions |
The project has a comprehensive test suite with 1,582 tests (1,058 Python + 524 JavaScript) covering unit, integration, system, and UI testing.
cd scrum-journal
./setup-tests.sh # installs Python + JS test deps, runs smoke tests# All Python tests
source .venv/bin/activate
python -m pytest tests/ -v
# All JavaScript tests
npx jest --verbose --forceExit
# Both with coverage reports
./run-coverage.sh- Unit tests — isolated per-module tests with mocked dependencies
- Integration tests — cross-module pipelines with real DB, only external services mocked
- System tests — full end-to-end user workflows (onboarding, standup, weekly summary, GitHub import, critique generation, data export/import, multi-user scenarios)
- E2E tests — browser-like end-to-end flows
- Scenario tests — multi-step real-world usage scenarios
- UI tests — Jest+jsdom tests for all frontend JavaScript modules
Tests run automatically on every push to main and on pull requests via GitHub Actions. In-progress runs are cancelled when new commits are pushed.