Developer productivity and reflection toolkit. The goal of this project is to provide a minimal command line interface and supporting documents that help developers stay focused and keep short personal notes during a work session.
Workflow: feature → development → main (release, tag).
All work starts on short-lived feature branches that merge into development.
Release branches target main. Commits use a commit-msg hook to append
SquirrelFocus trailers, enabling workflows to summarize the latest
journal_logs entry. CI runs on pushes and pull requests for development
and main, and merging to main appends a line to MILESTONE_LOG.md.
The main and development branches are protected. Merges require pull
requests and passing checks.
Run bash scripts/install_hooks.sh to install the hook on Unix-like
systems. Windows users can run pwsh scripts/install_hooks.ps1 to set up
the hook.
- Python 3.10 or newer
- Poetry for dependency management. The
setup.shhelper will install it automatically if it is missing.
Clone the repository and run the helper script. The script installs Poetry if needed and then installs the project dependencies:
./setup.shAfter the script completes run a quick greeting to verify the setup:
poetry run sf helloIf the setup complains about lock-file changes run poetry lock and try
again. See docs/troubleshooting.md for details.
If you prefer to manage Poetry yourself you can still run poetry install
manually. Skipping the project package keeps the environment lightweight:
poetry install --no-rootYou can achieve the same behavior permanently by setting
package-mode = false in your Poetry configuration. When skipping the
package installation, the sf entry point is not available. Invoke the
CLI module directly instead:
poetry run python -m cli helloIf you do install the package (or enable package mode) the original entry point will work as before:
poetry run sf hellopoetry run sf init --with-hook --with-workflows
poetry run sf new --fix "parser bug"
poetry run sf preview
poetry run sf doctorWindows users can install the commit hook:
pwsh scripts/install_hooks.ps1Some commands rely on external services such as the OpenAI API or a Discord
webhook. Copy .env.example to .env and supply your credentials before
running those features. The file includes placeholders for the following
variables:
OPENAI_API_KEY=your-api-key
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...GitHub Actions use this key as a secret. Add OPENAI_API_KEY to the
repository secrets so the automated workflows can run correctly.
After installing the project you can invoke the CLI using Poetry's run
command:
poetry run sf helloSee docs/cli_reference.md for command details.
Shell completions are available with --install-completion and can be
inspected with --show-completion.
The default command prints a friendly greeting. Use drop to store a note and
show to display recent entries. The ask command requires an
OPENAI_API_KEY environment variable and turns a question into a work item:
poetry run sf drop "Fixed a tricky bug"
poetry run sf show 3
poetry run sf ask "How do I plan tomorrow?"Daily reflections live in codex/journal. Each entry lists metadata such as date, tags and a short summary in a YAML header.
See the Codex goals document
Codex goals
for how sf ask converts prompts into tasks.
- Vision outlines the goals and value of the project.
- Security Overview explains data handling.
Common development tasks can be run through Poetry:
# Format and lint the code
poetry run black .
poetry run ruff check .
# Run the test suite
poetry run pytest
# Run the test suite with coverage
poetry run pytest --cov=. --cov-report=term-missingUse the reusable workflow to generate summaries in other workflows:
jobs:
summarize:
uses: ./.github/workflows/sf-summary.yml
with:
title: "Example title"
secrets: inheritThe job accepts a title describing the context for the summary.
See docs/troubleshooting.md for common errors.
MIT License © 2024–2025. See LICENSE for full text.