Create Your First Project

Welcome to Hagicode! After installation, let’s create your first project. This guide will walk you through the setup step by step, from preparing the code repository to initializing OpenSpec, just like a friend teaching you hand by hand.

Prerequisites

Before creating your first project, make sure you have:

• A code repository you want to manage with Hagicode
• Git installed and configured
• Basic understanding of command line operations

Don’t worry, these are all simple!

Step 1: Prepare Your Code Repository

Before adding a project to Hagicode, you need to prepare a code repository that you want to manage with Hagicode.

Clone Your Code Repository

If the code you want to manage is already in a remote repository (GitHub, GitLab, etc.), clone it locally:

# Clone your code repository locally
git clone https://github.com/your-username/your-repo.git
cd your-repo

After cloning, note down the repository’s local path (e.g., C:\Users\YourName\Projects\your-repo or /home/yourname/projects/your-repo), you will need this path in the next step.

Tip

Hagicode is suitable for managing any code project you want to assist in development and optimization with AI, including:

• Feature projects currently under development
• Existing code that needs refactoring or optimization
• Projects for team collaboration
• Personal open source projects

If Your Code is Only Local

If the code you want to manage is still local and hasn’t been pushed to a remote repository:

cd /path/to/your/project
git init
git add .
git commit -m "Initial commit"

It is recommended to create a remote repository on GitHub/GitLab and push:

git remote add origin https://github.com/your-username/your-repo.git
git push -u origin main

Step 2: Add Project in Hagicode Interface

Now let’s add the project to the Hagicode interface.

Access Project Page

1. Navigate to http://127.0.0.1:34567 in your browser
2. Click Projects in the navigation sidebar
3. Click the Add Project button

Configure Project Settings

Fill in project information:

Note

The repository path must point to a valid Git repository on your local computer.

Docker Compose Deployment Notes

If you are using the Docker Compose deployment method, you need to pay attention when filling in the repository path:

• Use container path: Fill in the path inside the container, not the host’s path
• Path mapping relationship: Based on the path mapping configuration in docker-compose.yml
  • Host path: /path/to/your/repos (configured by you in docker-compose.yml)
  • Container path: /app/workdir (fixed path)

Example: If your docker-compose.yml is configured as:

volumes:
  - /home/user/myproject:/app/workdir

Then when filling in the repository path, you should use the container path:

/app/workdir

Important Tips:

• Ensure your code repository is mapped to the /app/workdir path in the container
• If using software package deployment method, just fill in the actual path on the host

Create Project

After filling in the required information:

1. Click the Create Project button to add the project
2. Hagicode will verify the repository path
3. Your project will appear in the project list

Step 3: Initialize SDD

SDD (Software Design Document) is an important component in Hagicode for managing project design and changes. Initializing SDD in a project creates the necessary structure for managing changes.

Run SDD Initialization

In the project overview, find the SDD section:

1. Click the project’s SDD tab

2. Click the Initialize SDD button

Step 4: Optimize project.md

Hagicode will automatically optimize the project.md file for you, adding detailed project information and prompt configuration.

Run Optimization

1. On the project details page, click the Optimize button in the upper right corner

2. Hagicode will automatically analyze your code repository and generate optimized project.md content

Note

The optimization process may take a long time, depending on your project scale and complexity. After clicking the optimize button, you can temporarily leave, and Hagicode will complete the optimization work in the background.

Step 5: Commit to Version Control

After completing SDD initialization and project.md optimization, you need to commit these important configuration files to your version control system.

Commit All Changes

Commit all generated files and optimized configuration to your repository:

cd /path/to/your/project
git add .
git commit -m "Initialize SDD and optimize project.md"

Tip

It is very important to keep these files in version control because:

• SDD related files contain the project’s proposals, specifications, and change management structure, ensuring team collaboration and change tracking
• project.md file contains important project metadata and AI interaction prompt configuration, which is key to Hagicode’s normal operation

By incorporating these files into version control, you can ensure that the entire team uses consistent configuration and fully records all design and decision processes of the project.

Next Steps

Congratulations! You have created your first project in Hagicode. Here are some recommended next steps:

• Conversation Session - Learn how to use AI-driven coding sessions
• Proposal Session - Deep dive into managing proposals