# Quaestor
> 🏛️ Keep your AI assistant on track and actually useful
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/quaestor/)
Quaestor gives your AI assistant the context it needs to actually help you code. It analyzes your project, generates smart documentation, and keeps Claude from going off the rails.
## 🎯 Why?
Ever had Claude forget what you were working on? Or suggest patterns that don't match your codebase? Yeah, us too.
Quaestor fixes that by:
- **🧠 Understanding your code**: Detects your stack, patterns, and architecture automatically
- **📚 Keeping context**: Maintains what's been done and what's next across sessions
- **🎮 Enforcing standards**: Makes sure AI follows YOUR project's patterns, not generic ones
- **📊 Tracking progress**: Knows what's done, what's in progress, what's next
- **✅ Quality gates**: Won't let AI claim "done" until tests pass and linters are happy
## 📦 Installation
### Quickest (no install needed)
```bash
# Just run it
uvx quaestor init
```
### If you want it installed
```bash
# Global install with uv
uv tool install quaestor
# Or add to your project
uv add quaestor
# Old school pip works too
pip install quaestor
```
## 🚀 Getting Started
### 1. Initialize in your project:
```bash
quaestor init
```
This will:
- 🔍 Scan your code to figure out what you're building
- 💬 Ask a few smart questions based on what it finds
- 📝 Generate context files that AI assistants actually understand
- ✨ Set you up for success
### 2. What you get:
- `CLAUDE.md` - Instructions for your AI assistant (root dir so Claude auto-reads it)
- `.quaestor/ARCHITECTURE.md` - Your actual architecture (not hallucinated)
- `.quaestor/MEMORY.md` - What's been done, what's next
- `.quaestor/commands/` - Battle-tested workflows
### 3. Just start coding:
When you open your project with Claude, it automatically reads these files and knows:
- Your project structure
- Your coding standards
- What you're working on
- How to test and validate changes
## 📁 What goes where
```
your-project/
├── CLAUDE.md # AI reads this first
└── .quaestor/
├── ARCHITECTURE.md # Your real architecture
├── MEMORY.md # Progress tracking
└── commands/ # Workflows that work
├── project-init.md # Smart project analysis
├── task-py.md # Python workflows
├── task-rs.md # Rust workflows
├── check.md # Quality checks
└── compose.md # Template combos
```
## 🌟 What it does
### Right now
- **🔍 Smart Analysis**:
- Figures out your stack (React? Django? FastAPI? etc.)
- Detects your patterns (MVC? DDD? Microservices?)
- Finds your tools (PostgreSQL? Redis? Docker?)
- **🤖 Context Generation**:
- Writes docs FROM your code, not assumptions
- Tracks progress from git history
- Asks the right questions
- **📝 AI-Friendly Format**:
- Special markers for precise edits
- Structured data that won't get mangled
- Designed for LLMs, not humans
- **🎯 Command System**:
- `init` - Smart setup with code analysis
- `task-py` / `task-rs` - Language-specific workflows
- `check` - Make sure everything's clean
- `compose` - Combine templates for complex stuff
- `milestone-commit` - Auto-commit completed work with PRs
### Coming soon
- **Git Review**: Automated PR reviews that actually understand your code
- **Auto Docs**: Keep docs in sync with code automatically
- **More Languages**: task-js, task-go, etc.
- **Team Sync**: Share context across your team
## 🏗️ How it actually works
### When you run `quaestor init`:
1. **Scans your project**:
- Looks for package.json, requirements.txt, Cargo.toml, etc.
- Detects frameworks from imports and dependencies
- Figures out your architecture from folder structure
2. **Asks smart questions**:
- Only asks what it can't figure out
- Questions based on what it found
- Skips the obvious stuff
3. **Generates real docs**:
- Architecture based on your actual code
- Progress from your git history
- Standards from your existing patterns
### The special format
We use a markdown format that LLMs can reliably parse and edit:
```markdown
<!-- SECTION:architecture:database:START -->
```yaml
database:
type: PostgreSQL
orm: SQLAlchemy
migrations: Alembic
```
<!-- SECTION:architecture:database:END -->
```
This lets AI make precise edits without breaking your docs.
## 🔗 Part of something bigger
Quaestor is part of Praetor - tools for engineers who actually like coding but want AI to handle the boring stuff. You stay in control, AI does the grunt work. It's just that most of it is my head.
## 💻 Contributing
```bash
# Get the code
git clone https://github.com/jeanluciano/quaestor.git
cd quaestor
# Setup
uv sync
# Test it
uv run pytest
# Try it
uv run python main.py init
```
## 📚 Command Templates
- **`project-init.md`** - Analyzes your project and sets everything up
- **`task-py.md`** - Python implementation with all the checks
- **`task-rs.md`** - Rust implementation with clippy and all
- **`check.md`** - Fix all the things
- **`compose.md`** - Combine templates for complex operations
- **`milestone-commit.md`** - Auto-commit completed TODOs and create PRs
### 🔄 Workflow Hooks
Quaestor now includes automatic workflow hooks that trigger after certain events:
- **After completing a TODO**: Automatically commits your work
- **After updating MEMORY.md**: Checks for completed items and commits them
- **When milestone is complete**: Creates a pull request automatically
These hooks are configured in `CLAUDE.md` and integrated into the task commands. They ensure:
- Clean git history with atomic commits
- Automatic quality checks before commits
- Progress tracking stays in sync
- PRs are created when milestones are done
## 📄 License
[MIT](LICENSE) - Use it however you want.
## 🤝 Contributing
PRs welcome! Just make sure tests pass and linters are happy.
Raw data
{
"_id": null,
"home_page": null,
"name": "quaestor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ai, development, context, claude, project-management, ai-tools",
"author": null,
"author_email": "Jean Luciano <jeanluciano@example.com>",
"download_url": "https://files.pythonhosted.org/packages/73/87/9fdc5f8dcbc2b58eab7a5af2feab445f6dd142a765b697b66c80bd0f3ce8/quaestor-0.2.0.tar.gz",
"platform": null,
"description": "# Quaestor\n\n> \ud83c\udfdb\ufe0f Keep your AI assistant on track and actually useful\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/quaestor/)\n\nQuaestor gives your AI assistant the context it needs to actually help you code. It analyzes your project, generates smart documentation, and keeps Claude from going off the rails.\n\n## \ud83c\udfaf Why?\n\nEver had Claude forget what you were working on? Or suggest patterns that don't match your codebase? Yeah, us too.\n\nQuaestor fixes that by:\n\n- **\ud83e\udde0 Understanding your code**: Detects your stack, patterns, and architecture automatically\n- **\ud83d\udcda Keeping context**: Maintains what's been done and what's next across sessions\n- **\ud83c\udfae Enforcing standards**: Makes sure AI follows YOUR project's patterns, not generic ones\n- **\ud83d\udcca Tracking progress**: Knows what's done, what's in progress, what's next\n- **\u2705 Quality gates**: Won't let AI claim \"done\" until tests pass and linters are happy\n\n## \ud83d\udce6 Installation\n\n### Quickest (no install needed)\n```bash\n# Just run it\nuvx quaestor init\n```\n\n### If you want it installed\n```bash\n# Global install with uv\nuv tool install quaestor\n\n# Or add to your project\nuv add quaestor\n\n# Old school pip works too\npip install quaestor\n```\n\n## \ud83d\ude80 Getting Started\n\n### 1. Initialize in your project:\n```bash\nquaestor init\n```\n\nThis will:\n- \ud83d\udd0d Scan your code to figure out what you're building\n- \ud83d\udcac Ask a few smart questions based on what it finds\n- \ud83d\udcdd Generate context files that AI assistants actually understand\n- \u2728 Set you up for success\n\n### 2. What you get:\n- `CLAUDE.md` - Instructions for your AI assistant (root dir so Claude auto-reads it)\n- `.quaestor/ARCHITECTURE.md` - Your actual architecture (not hallucinated)\n- `.quaestor/MEMORY.md` - What's been done, what's next\n- `.quaestor/commands/` - Battle-tested workflows\n\n### 3. Just start coding:\nWhen you open your project with Claude, it automatically reads these files and knows:\n- Your project structure\n- Your coding standards\n- What you're working on\n- How to test and validate changes\n\n## \ud83d\udcc1 What goes where\n\n```\nyour-project/\n\u251c\u2500\u2500 CLAUDE.md # AI reads this first\n\u2514\u2500\u2500 .quaestor/\n \u251c\u2500\u2500 ARCHITECTURE.md # Your real architecture\n \u251c\u2500\u2500 MEMORY.md # Progress tracking\n \u2514\u2500\u2500 commands/ # Workflows that work\n \u251c\u2500\u2500 project-init.md # Smart project analysis\n \u251c\u2500\u2500 task-py.md # Python workflows\n \u251c\u2500\u2500 task-rs.md # Rust workflows\n \u251c\u2500\u2500 check.md # Quality checks\n \u2514\u2500\u2500 compose.md # Template combos\n```\n\n## \ud83c\udf1f What it does\n\n### Right now\n\n- **\ud83d\udd0d Smart Analysis**: \n - Figures out your stack (React? Django? FastAPI? etc.)\n - Detects your patterns (MVC? DDD? Microservices?)\n - Finds your tools (PostgreSQL? Redis? Docker?)\n \n- **\ud83e\udd16 Context Generation**:\n - Writes docs FROM your code, not assumptions\n - Tracks progress from git history\n - Asks the right questions\n \n- **\ud83d\udcdd AI-Friendly Format**: \n - Special markers for precise edits\n - Structured data that won't get mangled\n - Designed for LLMs, not humans\n \n- **\ud83c\udfaf Command System**: \n - `init` - Smart setup with code analysis\n - `task-py` / `task-rs` - Language-specific workflows \n - `check` - Make sure everything's clean\n - `compose` - Combine templates for complex stuff\n - `milestone-commit` - Auto-commit completed work with PRs\n\n### Coming soon\n\n- **Git Review**: Automated PR reviews that actually understand your code\n- **Auto Docs**: Keep docs in sync with code automatically\n- **More Languages**: task-js, task-go, etc.\n- **Team Sync**: Share context across your team\n\n## \ud83c\udfd7\ufe0f How it actually works\n\n### When you run `quaestor init`:\n\n1. **Scans your project**:\n - Looks for package.json, requirements.txt, Cargo.toml, etc.\n - Detects frameworks from imports and dependencies\n - Figures out your architecture from folder structure\n\n2. **Asks smart questions**:\n - Only asks what it can't figure out\n - Questions based on what it found\n - Skips the obvious stuff\n\n3. **Generates real docs**:\n - Architecture based on your actual code\n - Progress from your git history\n - Standards from your existing patterns\n\n### The special format\n\nWe use a markdown format that LLMs can reliably parse and edit:\n\n```markdown\n<!-- SECTION:architecture:database:START -->\n```yaml\ndatabase:\n type: PostgreSQL\n orm: SQLAlchemy\n migrations: Alembic\n```\n<!-- SECTION:architecture:database:END -->\n```\n\nThis lets AI make precise edits without breaking your docs.\n\n## \ud83d\udd17 Part of something bigger\n\nQuaestor is part of Praetor - tools for engineers who actually like coding but want AI to handle the boring stuff. You stay in control, AI does the grunt work. It's just that most of it is my head.\n\n## \ud83d\udcbb Contributing\n\n```bash\n# Get the code\ngit clone https://github.com/jeanluciano/quaestor.git\ncd quaestor\n\n# Setup\nuv sync\n\n# Test it\nuv run pytest\n\n# Try it\nuv run python main.py init\n```\n\n## \ud83d\udcda Command Templates\n\n- **`project-init.md`** - Analyzes your project and sets everything up\n- **`task-py.md`** - Python implementation with all the checks\n- **`task-rs.md`** - Rust implementation with clippy and all\n- **`check.md`** - Fix all the things\n- **`compose.md`** - Combine templates for complex operations\n- **`milestone-commit.md`** - Auto-commit completed TODOs and create PRs\n\n### \ud83d\udd04 Workflow Hooks\n\nQuaestor now includes automatic workflow hooks that trigger after certain events:\n\n- **After completing a TODO**: Automatically commits your work\n- **After updating MEMORY.md**: Checks for completed items and commits them\n- **When milestone is complete**: Creates a pull request automatically\n\nThese hooks are configured in `CLAUDE.md` and integrated into the task commands. They ensure:\n- Clean git history with atomic commits\n- Automatic quality checks before commits\n- Progress tracking stays in sync\n- PRs are created when milestones are done\n\n## \ud83d\udcc4 License\n\n[MIT](LICENSE) - Use it however you want.\n\n## \ud83e\udd1d Contributing\n\nPRs welcome! Just make sure tests pass and linters are happy.\n",
"bugtrack_url": null,
"license": null,
"summary": "AI-assisted development context management tool for maintaining consistency and productivity",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/jeanluciano/quaestor",
"Issues": "https://github.com/jeanluciano/quaestor/issues",
"Repository": "https://github.com/jeanluciano/quaestor"
},
"split_keywords": [
"ai",
" development",
" context",
" claude",
" project-management",
" ai-tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "720e3c1c567138d1216184ba0a6ad21bad368698e8a596adf367f275a1559247",
"md5": "3f5a1d11fe6b5c9ce4f4526b706b7439",
"sha256": "deefec63b50a26a8d699041f5f1c0c82238faf7216709378d22ee3038dd7321b"
},
"downloads": -1,
"filename": "quaestor-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f5a1d11fe6b5c9ce4f4526b706b7439",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 58383,
"upload_time": "2025-07-09T02:38:28",
"upload_time_iso_8601": "2025-07-09T02:38:28.676130Z",
"url": "https://files.pythonhosted.org/packages/72/0e/3c1c567138d1216184ba0a6ad21bad368698e8a596adf367f275a1559247/quaestor-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "73879fdc5f8dcbc2b58eab7a5af2feab445f6dd142a765b697b66c80bd0f3ce8",
"md5": "87b275bab20f8f716034975f11950a15",
"sha256": "b031b731c08e7ad5573a3a23c441d6bb98ca3f14c5cb6e50d5ffe054b8acff49"
},
"downloads": -1,
"filename": "quaestor-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "87b275bab20f8f716034975f11950a15",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 53696,
"upload_time": "2025-07-09T02:38:29",
"upload_time_iso_8601": "2025-07-09T02:38:29.981587Z",
"url": "https://files.pythonhosted.org/packages/73/87/9fdc5f8dcbc2b58eab7a5af2feab445f6dd142a765b697b66c80bd0f3ce8/quaestor-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 02:38:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeanluciano",
"github_project": "quaestor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "quaestor"
}
JSON
