AI conversations through Markdown files.
Write thoughts in markdown, reference files [[path]] and URLs [[url]], run the ask CLI tool, and Claude AI responds directly in your file. Markdown is the AI conversation — editable, searchable, and flexible.
- Create a
session.mdfile. - Edit
session.mdin an editor. - Run
askat a terminal.
Here's a session.md file before running ask.
# [1] Human
I'm refactoring an authentication module.
[[src/auth/]]
What are some well-factored approaches?After running ask, your files expand and Claude AI streams a response to your file.
# [1] Human
I'm refactoring an authentication module.
<!-- dir: src/auth/ -->
### src/auth/login.ts
...
### src/auth/session.ts
...
<!-- /dir -->
What are some well-factored approaches?
# [2] AI
Looking at your current implementation, I'd suggest...
# [3] Human
Add your next thought to the # [3] Human section, and run ask again.
That's the whole loop: think, write, ask, continue.
macOS:
curl -L https://github.com/rana/ask/releases/latest/download/ask-darwin-arm64.tar.xz | tar xJ
sudo mv ask /usr/local/bin/Linux:
curl -L https://github.com/rana/ask/releases/latest/download/ask-linux-amd64.tar.xz | tar xJ
sudo mv ask /usr/local/bin/Windows: Download from releases, extract, add to PATH.
aws configure # Setup AWS credentials (needs Bedrock access)
ask init # Create session.md
# Edit session.md with your question
ask # Run the conversationReference files and URLs with [[path]]. They expand inline when you run ask.
| Pattern | Expands to |
|---|---|
[[file.ts]] |
Single file |
[[src/]] |
Directory (non-recursive) |
[[src/**/]] |
Directory (recursive) |
[[https://...]] |
Web page content |
Explain this function:
[[src/lib/parser.ts]]
Review the entire module:
[[src/auth/**/]]
Based on this documentation:
[[https://docs.example.com/api]]Comments and headers are stripped by default to reduce tokens. Disable with ask cfg filter off.
To refresh expanded content: ask refresh
ask cfg # View current settings
ask cfg model sonnet # Switch model (opus/sonnet/haiku)
ask cfg temperature 0.7 # Adjust creativity (0.0-1.0)
ask cfg filter off # Keep comments in expanded files
ask cfg web off # Disable URL fetchingRun ask help cfg for all options.
ask uses Claude through AWS Bedrock. You need:
- AWS account with Bedrock access enabled
- Claude models activated in your region
- Credentials configured
aws configure
# Enter: Access Key ID, Secret Access Key, region (e.g., us-west-2)$ ask help
ask — AI conversations through Markdown
Usage
ask [command] [options]
Commands
chat Continue the conversation in a session file (default)
init Initialize a new session file
cfg View or update configuration
refresh Refresh all expanded file, directory, and URL references
version Show version information
help Show help information
Examples
$ ask Continue conversation
$ ask init Start new session
$ ask -m sonnet Use specific model
$ ask help cfg Command help
Run ask help <command> for detailsThe session file is a source of truth — not a database, not a chat window. Thinking lives in markdown where you work.
ask stays out of your way. Write naturally, reference what matters, let Claude respond in the same file. Different conversations save to different files. Keep it simple.