Devseeker

DevSeeker is a coding agent inspired by claude code and aider

devseeker can :

• manage code files and folders
• Create and edit code on command
• Store code in short-term memory
• review code changes
• run code files
• calculate token usage
• offer multiple coding modes
• support wide range of ai models

a little demo

devseekerr.mp4

rare video of me losing a little game devseeker made :(

Table of Contents

• Installation
• Configuration
• Basic Usage
• Operational Modes
• CLI Options Reference
• Environment Variables
• Using Alternative Models
• Project Configuration
• File Selection
• Troubleshooting
• Windows-Specific Instructions
• Contributing
• License

Installation

Via pip (Recommended)

pip install devseeker

Development Installation

git clone https://github.com/iBz-04/devseeker.git
cd devseeker
poetry install
poetry env activate

Configuration

DevSeeker requires an OpenAI API key. You can set it in three ways:

1. Environment variable

export OPENAI_API_KEY=your_api_key

2. .env file

Create a .env file in your project directory:

OPENAI_API_KEY=your_api_key

3. Custom configuration

For advanced configuration, create a devseeker.toml file in your project:

[run]
build = "npm run build"
test = "npm run test"
lint = "quick-lint-js"

[paths]
base = "./src"  # base directory to operate in

Basic Usage

Creating a New Project

1. Create an empty directory for your project
2. Inside the directory, create a file named prompt containing your instructions
3. Run DevSeeker:

devseeker projects/my-new-project

When you run this command, DevSeeker will:

• Present a welcome interface
• Read your prompt (or ask for one if not found)
• Generate code files based on your description
• Create an entrypoint file for running the project
• Ask if you want to execute the generated code

Improving Existing Code

devseeker projects/my-existing-project -i

When you run DevSeeker in improve mode with the -i flag, it provides an interactive terminal UI that allows you to:

1. Describe how you want to improve your application through natural language prompts
2. Select which files should be modified (through an interactive file selection interface)
3. Review proposed changes in a diff view (showing what will be added/removed)
4. Accept or reject the changes before they're applied to your codebase

You can also use the --skip-file-selection or -s flag to bypass the interactive file selection:

devseeker projects/my-existing-project -i -s

Operational Modes

DevSeeker supports several operational modes that change how it processes your prompts and generates code:

Standard Mode (Default)

Generates complete projects following your prompt.

devseeker projects/my-project

Improve Mode

Modifies existing code according to your instructions.

devseeker projects/my-project -i

Clarify Mode

Discusses specifications with you before implementing them.

devseeker projects/my-project -c

Lite Mode

Generates code using only your main prompt, without additional steps.

devseeker projects/my-project -l

Self-Heal Mode

Automatically fixes code when it fails during execution.

devseeker projects/my-project -sh

CLI Options Reference

DevSeeker offers numerous command-line options to customize its behavior:

Option	Short	Default	Description
--model,	-m	gpt-4o	The AI model to use
--temperature	-t	0.1	Controls randomness in outputs (0.0-1.0)
--improve	-i	False	Improves existing project
--lite	-l	False	Runs using only the main prompt
--clarify	-c	False	Discusses specifications before implementation
--self-heal	-sh	False	Auto-fixes failing code
--azure	-a	""	Azure OpenAI endpoint URL
--use-custom-preprompts		False	Uses custom prompts from project workspace
--llm-via-clipboard		False	Uses clipboard for AI communication
--verbose	-v	False	Enables verbose logging
--debug	-d	False	Enables debug mode
--prompt_file		"prompt"	Path to text file with prompt
--entrypoint_prompt		""	Path to file with entrypoint requirements
--image_directory		""	Path to folder with images
--use_cache		False	Caches LLM responses to save tokens
--skip-file-selection	-s	False	Skips interactive file selection in improve mode
--no_execution		False	Runs setup without calling LLM or writing code
--sysinfo		False	Outputs system information for debugging
--diff_timeout		3	Timeout for diff regexp searches
--help	-h		Shows help information

Common Command Examples

# Basic usage - create a project from prompt
devseeker projects/my-project

# Create a project with a specific model
devseeker projects/my-project -m gpt-4-turbo

# Improve an existing project
devseeker projects/my-existing-project -i

# Improve a project with higher temperature for more creative outputs
devseeker projects/my-project -i -t 0.5

# Clarify requirements before implementation
devseeker projects/my-project -c

# Use lite mode for faster generation
devseeker projects/my-project -l

# Enable self-healing for auto-fixing code
devseeker projects/my-project -sh

# Use Azure OpenAI service
devseeker projects/my-project --azure https://<your-resource-name>.openai.azure.com

# Display help information
devseeker --help

# Display system information for troubleshooting
devseeker --sysinfo

# Skip file selection in improve mode
devseeker projects/my-project -i -s

# Use a specific prompt file
devseeker projects/my-project --prompt_file custom_prompt.txt

# Use images in your prompt
devseeker projects/my-project --image_directory images/

# Use custom preprompts
devseeker projects/my-project --use-custom-preprompts

# Enable verbose logging
devseeker projects/my-project -v

Environment Variables

DevSeeker recognizes these environment variables:

Variable	Description
OPENAI_API_KEY	Your OpenAI API key
MODEL_NAME	Default model to use (e.g., "gpt-4o")
OPENAI_API_BASE	Alternative API endpoint
LOCAL_MODEL	Set to "true" when using local models
EDITOR	Your preferred text editor
LANGCHAIN_WANDB_TRACING	Enable W&B tracing (set to "true")
WANDB_API_KEY	Weights & Biases API key

Using Alternative Models

Local Models with llama.cpp

export OPENAI_API_BASE="http://localhost:8000/v1"
export OPENAI_API_KEY="sk-your_local_key"
export MODEL_NAME="CodeLlama"
export LOCAL_MODEL=true

Azure OpenAI

devseeker --azure https://<your-resource-name>.openai.azure.com my-project

See docs/open_models.md for detailed instructions.

Project Configuration

DevSeeker can be configured with a devseeker.toml file in your project root:

[run]
build = "npm run build"
test = "npm run test"
lint = "quick-lint-js"

[paths]
base = "./frontend"  # base directory for monorepos
src = "./src"        # source directory for context

[devseeker-app]      # used for devseeker.app integration
project_id = "..."

File Selection

When improving code, DevSeeker needs to know which files to include in its context. The file selection process:

1. DevSeeker scans your project directory
2. Creates a TOML file with file paths
3. Opens this file in your text editor
4. You uncomment lines for files you want to include
5. Save and close the file to continue

The selection interface supports:

• Color-coded file types
• Intelligent defaults based on language
• Filtering of common directories like node_modules

Troubleshooting

Common Issues

API Key Not Found

Error: OpenAI API key not found

Solution: Set your OPENAI_API_KEY as described in Configuration.

Token Limit Exceeded

Error: This model's maximum context length is exceeded

Solution: Select fewer files in improve mode or use a model with higher token limits.

Execution Errors

If generated code fails to run, try:

• Using self-heal mode: devseeker path/to/project -sh
• Checking dependency installation
• Inspecting generated logs in the project's .devseeker/logs directory

Windows-Specific Instructions

Windows users should consult WINDOWS_README.md for platform-specific details.

Key differences:

• Use set instead of export for environment variables
• Path separators use backslashes
• Some commands may require PowerShell

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License. See LICENSE for details.