Using .goosehints Files with Goose 🦢

Introduction

According to the official goose website, Goose 🦢 is a developer agent that supercharges your software development by automating an array of coding tasks directly within your terminal or IDE. Guided by you, it can intelligently assess your project's needs, generate the required code or modifications, and implement these changes on its own. Goose can interact with a multitude of tools via external APIs such as Jira, GitHub, Slack, infrastructure and data pipelines, and more -- if your task uses a shell command or can be carried out by a Python script, Goose can do it for you too! Like semi-autonomous driving, Goose handles the heavy lifting, allowing you to focus on other priorities. Simply set it on a task and return later to find it completed, boosting your productivity with less manual effort. In this post, we’ll explore what .goosehints files are.

Learn more

What are .goosehints files and why use them

Understanding .goosehints

The hints file is meant to provide additional context about your project. The context can be user-specific or at the project level in which case, you can commit it to git.

A .goosehints file is a plain-text configuration file that provides Goose with supplemental information about your project. It acts as a guide to help Goose better understand the project’s structure, purpose, or even specific coding conventions you’re using. By providing Goose with additional context, you enable it to make smarter decisions, tailor its suggestions, and generate more accurate code or configurations.

For example, a .goosehints file might include:

• 
  Project-specific information: Key modules, folder structures, or domain knowledge.


• 
  Development conventions: Custom coding styles, naming conventions, or frameworks.


• 
  User preferences: Personal preferences for code formatting or tool usage.

Think of the .goosehints file as a guide that helps Goose better understand your project's structure, conventions, and requirements.

Why Use .goosehints?

Here’s why .goosehints files are a game-changer:

• 
  Enhanced Context: Goose performs best when it understands the nuances of your project. A .goosehints file provides the extra detail needed for Goose to make informed decisions.


• Consistency Across Teams: By committing a .goosehints file to your project’s repository, you ensure that all team members benefit from the same guidance. Goose will adhere to your project’s standards consistently, reducing discrepancies.


• User-Specific Customization: If you prefer personal preferences over global standards, you can create user-specific .goosehints files to tailor Goose’s behavior just for you.


• Time Savings: With a .goosehints file, Goose doesn’t need to ask repetitive questions or make assumptions. This saves time and ensures that tasks are completed faster.

Setting up .goosehints in Your Project

• Create the File
  

# At your project root

touch .goosehints

• Choose the Right Location
  Project-wide hints: Place in the root directory
  User-specific hints: Place in your home directory as ~/.goosehints
  Directory-specific hints: Place in relevant subdirectories

Basic Configuration Template

Start with this basic template and customize it for your needs:

project:

  name: "Your Project Name"

  repository: "https://github.com/username/repo"

  type: "web-

Using Jinja templating in .goosehints

Goose 🦢 is powerful on its own, but its true potential shines when you combine it with dynamic and adaptable configurations. One way to achieve this is by incorporating Jinja templating into your .goosehints files. With Jinja, you can make your hints dynamic, reusable, and adaptable to various environments or user preferences.

What Is Jinja Templating?

Jinja is a Python-based templating engine that allows you to use placeholders and logic (e.g., loops, conditions) in your text files. It’s widely used in web frameworks like Flask and tools like Ansible, and it’s perfect for creating dynamic .goosehints files.

Learn more

By embedding Jinja in your .goosehints, you can:

• Dynamically adjust hints based on environment variables or user input.


• Reuse templates across multiple projects.


• Add logic to make .goosehints files more modular and flexible.

Why Use Jinja in .goosehints?

Here are some benefits of using Jinja templating in your .goosehints file:

• 
  Dynamic Configuration: Adjust hints for different environments (e.g., staging, production) without editing the file manually.


• 
  Reusability: Use the same .goosehints template across multiple projects by dynamically injecting project-specific details.


• 
  Customization: Enable developers to pass in their own variables for more personalized hints.


• 
  Reduced Redundancy: Use loops and macros to simplify repetitive structures in your hints.

Setting Up Jinja in .goosehints

• Enable Jinja Rendering in Goose
  To use Jinja in .goosehints, you need to ensure Goose is configured to process Jinja templates. While Goose typically supports templating natively, check the documentation to verify it’s enabled or use the appropriate flag:
  

goose --hints-file .goosehints --enable-jinja  

If you’re using an external file renderer, you may also process the file manually before passing it to Goose:

jinja2 .goosehints.template --format=json > .goosehints  

goose --hints-file .goosehints  

• Writing a .goosehints Template

A .goosehints file using Jinja templating looks similar to a regular .goosehints file but includes Jinja-specific syntax.

Here’s an example:

• Environment-Specific Configuration example
  

# Project Information  

Project Name: {{ project_name }}  

Environment: {{ environment }}  



# Framework  

Framework: {{ framework }}  

Version: {{ framework_version }}  



# Key Modules  

{% for module in modules %}  

- {{ module.name }}: {{ module.description }}  

{% endfor %}  



# Preferences  

- Code Formatting: {{ preferences.code_formatting }}  

- Add Comments to Migrations: {{ preferences.comments }}  

Rendering the File

To render this file, you’ll need to provide the required variables (e.g., via a .json or .yaml file).

jinja2 .goosehints.template -D project_name="Ticket Manager" -D environment="production" \

-D framework="Django" -D framework_version="4.2" \

-D modules='[{"name": "events", "description": "Handles events"}, {"name": "users", "description": "User management"}]' \

-D preferences='{"code_formatting": "PEP8", "comments": "Yes"}' > .goosehints  

The rendered .goosehints file would look like this:

# Project Information  

Project Name: Ticket Manager  

Environment: production  



# Framework  

Framework: Django  

Version: 4.2  



# Key Modules  

- events: Handles events  

- users: User management  



# Preferences  

- Code Formatting: PEP8  

- Add Comments to Migrations: Yes  

Advanced Jinja Features for .goosehints

Jinja offers powerful features to make your .goosehints even more dynamic:

• 
  Conditionals
  

# Deployment Settings  

{% if environment == "production" %}  

Use Optimized Database Connections: Yes  

Enable Debug Mode: No  

{% else %}  

Use Optimized Database Connections: No  

Enable Debug Mode: Yes  

{% endif %}  

• 
  Loop
  

# Active Features  

{% for feature in active_features %}  

- {{ feature }}  

{% endfor %}  

• Macros

Reuse blocks of logic with macros:

{% macro module_info(module) %}  

- {{ module.name }}: {{ module.description }}  

{% endmacro %}  



# Key Modules  

{% for module in modules %}  

{{ module_info(module) }}  

{% endfor %}  

Best Practices for Jinja in .goosehints

• 
  Keep It Modular: Break down your .goosehints file into reusable sections using macros.


• 
  Validate Input Data: Ensure variables passed to the Jinja template are complete and correct.


• 
  Use Comments: Annotate complex logic in your .goosehints file for easier maintenance.


• Avoid Over-Engineering: Use Jinja only when necessary. For simple projects, a static .goosehints file may suffice.


• 
  Test Before Committing: Render the .goosehints file locally and verify it works as expected before committing to your repository.

Example Use Case: Multi-Environment .goosehints

Here’s an example of a .goosehints file designed for both staging and production environments:

# Project Info  

Project: {{ project_name }}  

Environment: {{ environment }}  



# Database Settings  

Database:  

{% if environment == "production" %}  

  Host: {{ production_db.host }}  

  Port: {{ production_db.port }}  

{% else %}  

  Host: {{ staging_db.host }}  

  Port: {{ staging_db.port }}  

{% endif %}  



# Logging Settings  

Log Level: {{ "DEBUG" if environment == "staging" else "INFO" }}  

Rendering Example:

jinja2 .goosehints.template -D project_name="MyApp" -D environment="staging" \

-D production_db='{"host": "prod-db.example.com", "port": 5432}' \

-D staging_db='{"host": "staging-db.example.com", "port": 5432}'  

Rendered file for staging:

# Project Info  

Project: MyApp  

Environment: staging  



# Database Settings  

Database:  

  Host: staging-db.example.com  

  Port: 5432  



# Logging Settings  

Log Level: DEBUG  

Project-level vs user-specific hints

Understanding the distinction between project-level and user-specific hints is crucial for maintaining a clean and efficient development environment. Each type serves different purposes and follows different management practices.

Project-Level Hints

Project-level hints are shared across all team members and are typically committed to version control.

Location and Naming

your-project/

├── .goosehints         # Main project hints

├── .goosehints.default # Template for user-specific hints

├── src/

└── ...

Appropriate Content for Project-Level Hints

# .goosehints

project:

  name: "example-project"

  repository: "https://github.com/org/example-project"



standards:

  code_style:

    indent: 2

    max_line_length: 80

    quotes: "single"



architecture:

  patterns:

    - "Repository pattern for data access"

    - "CQRS for complex operations"



testing:

  framework: "jest"

  coverage:

    minimum: 80

    excludes:

      - "src/types/"

      - "src/migrations/"



ci:

  required_checks:

    - "lint"

    - "test"

    - "build"

User-Specific Hints

User-specific hints contain personal preferences and local environment configurations. These should never be committed to version control.

Location and Naming

~/.goosehints                  # Global user hints

your-project/.goosehints.local # Project-specific user hints

Appropriate Content for User-Specific Hints

# .goosehints.local

editor:

  path: "/usr/local/bin/vim"

  config:

    theme: "monokai"

    line_numbers: true



local_env:

  database_url: "postgresql://localhost:5432/mydb"

  api_keys:

    service_a: "your-personal-key"

    service_b: "another-personal-key"



debug:

  verbose: true

  log_level: "debug"

  breakpoints:

    - "src/critical/function.ts"

    - "src/auth/login.ts"



shortcuts:

  build: "npm run build && npm run test"

  deploy: "kubectl apply -f ./my-local-config.yaml"

Managing Both Types

• Setup Template for New Team Members
  Create a .goosehints.default template:
  

# .goosehints.default

# Copy this file to .goosehints.local and customize

local_env:

  database:

    host: "localhost"

    port: 5432

    name: "project_db"

    # Add your username and password here

    username: ""

    password: ""



  services:

    cache:

      port: 6379

    queue:

      port: 5672



development:

  hot_reload: true

  mock_services: false  # Set to true if not running all services locally

• Git Configuration

Add to .gitignore:

# .gitignore

.goosehints.local

*/.goosehints.local

~/.goosehints

• Precedence Rules
  

# Priority order (highest to lowest):

# 1. .goosehints.local (user-specific, project directory)

# 2. ~/.goosehints (user-specific, global)

# 3. .goosehints (project-level)

# 4. .goosehints.default (template)

Best Practices and tips for Managing Hints

• Clear Separation of Concerns
  Project-Level (.goosehints)
  

# Things that should be consistent across all developers

standards:

  formatting:

    indent_style: "space"

    indent_size: 2



build:

  target_node: "16.x"

  optimization_level: "production"

User-Specific (.goosehints.local)

# Personal preferences and local setup

workspace:

  editor_command: "code"

  terminal: "iterm2"



debug:

  verbose_logging: true

  break_on_error: true

Documentation

Add comments in both files to help team members understand the purpose

# .goosehints

# Project-wide configuration that should be consistent across all developers.

# Changes to this file should be reviewed by the team.



# .goosehints.local

# Local developer configurations. Customize as needed.

# DO NOT commit this file to version control.

Migration and Updates

• Updating Project-Level Hints
  

# Create a pull request for project-level changes

git checkout -b update-hints

edit .goosehints

git commit -m "Update project hints: Add new testing standards"

git push origin update-hints

• Updating User-Specific Hints

Create a script to help users update their local hints

#!/bin/bash

# update-local-hints.sh



if [ -f .goosehints.local ]; then

  echo "Backing up current local hints..."

  cp .goosehints.local .goosehints.local.backup

fi



echo "Updating from default template..."

cp .goosehints.default .goosehints.local



echo "Please update your personal settings in .goosehints.local"

Real-World Examples

To better understand how to utilize .goosehints files with Goose 🦢, let’s explore some real-world scenarios where project-level and user-specific hints can make a significant difference. These examples demonstrate how .goosehints help automate workflows, maintain consistency, and streamline development tasks.

Web Development Team

A team is building a React application with a Node.js backend and PostgreSQL database. They want to enforce coding standards and automate development tasks across the project.

• Project-Level .goosehints

The team creates a .goosehints file in the project’s root directory to ensure consistency.

Framework: React  

Backend: Node.js  

Database: PostgreSQL  

Linting: ESLint  

Prettier: Enabled  

Test Command: npm test  

Build Command: npm run build  

Deploy Command: ./scripts/deploy.sh  

Directories:  

  - src/  

  - public/  

  - tests/  

  - scripts/  

How Goose Helps

• Automatically runs npm test before merging branches.


• Validates code style using ESLint and Prettier.



• Deploys the app using the ./scripts/deploy.sh script.




• User-Specific .goosehints

Developers can add their own .goosehints file for local preferences.

Editor: VS Code  

Node Path: /usr/local/bin/node  

Custom Command: npm run dev  

Personal Shortcut:  

  Start Server: npm start  

  Build App: npm run build  

How Goose Helps

• Automatically launches npm start when the developer opens the project.


• Suggests personalized shortcuts for frequent tasks.

Data Science Workflow

A team of data scientists is collaborating on a machine learning pipeline using Python, Jupyter Notebooks, and TensorFlow. They want Goose to handle repetitive setup and deployment tasks.

• Project-Level .goosehints

The team sets up a .goosehints file to define the environment and project structure.

Framework: TensorFlow  

Python Version: 3.10  

Virtual Environment: .venv/  

Install Command: pip install -r requirements.txt  

Train Model Command: python train.py  

Directories:  

  - notebooks/  

  - models/  

  - data/  

  - scripts/  

How Goose Helps

• Installs dependencies with pip install -r requirements.txt.
  
  Ensures everyone uses Python 3.10 with the .venv/ environment.
  
  Automates running python train.py during model training.




• User-Specific .goosehints

Individual data scientists use personal .goosehints files to customize their workflows.

Notebook Path: ~/projects/ml_project/notebooks  

Data Path: /mnt/data/  

Shortcut:  

  Open Notebook: jupyter notebook  

  Run All: python scripts/run_all.py  

How Goose Helps

• Opens Jupyter Notebooks in the specified path.


• Automates running run_all.py to preprocess data and train models.

Open Source Project Contributor

An open-source project is built using Django and has contributors from around the world. The project maintainers provide .goosehints to onboard new contributors quickly.

• Project-Level .goosehints

The maintainers define a .goosehints file in the repository to guide contributors.

Framework: Django  

Database: SQLite (for development)  

Python Version: 3.9  

Virtual Environment: venv/  

Runserver Command: python manage.py runserver  

Test Command: python manage.py test  

Linting: Enabled  

Directories:  

  - app/  

  - templates/  

  - static/  

  - tests/  

How Goose Helps

• Guides contributors in setting up the environment with python -m venv venv and installing dependencies.


• Runs python manage.py runserver to launch the local server.



• Enforces linting and test rules.




• User-Specific .goosehints

A contributor customizes their local configuration with a personal .goosehints file.

Editor: PyCharm  

Python Path: /usr/bin/python3  

Custom Command: python manage.py makemigrations  

Shortcut:  

  Start Server: python manage.py runserver --noreload  

  Run Tests: python manage.py test --verbosity=2  

How Goose Helps

• Suggests using --noreload for faster server restarts during debugging.


• Runs tests with detailed output using the --verbosity=2 flag.

Creative Uses for .goosehints

1. Interactive Documentation Generator


2. Team Onboarding Assistant


3. AI-Assisted Code Review Guide


4. Dynamic Testing Scenarios Generator


5. Development Workflow Automator

Join Goose Community.

Check out how to get Goose running if you are a window user here

If you want to know more about Goose, checkout